title: spec-review: Define output capture and audit trail

description:
Reviews happen in terminal then disappear. No audit trail, no diffable history.

Add:
- Guidance to tee output to review file (e.g., specs/{branch}/review.md)
- Standard location for gate check results
- Template for recording decisions and rationale

status: open

issue_type: task


title: Brainstorm agent-friendly doc conventions

description:
# Agent-Friendly Doc Conventions - Hybrid Architecture

## FINAL ARCHITECTURE: Vale + LLM Hybrid

### Insight
> "Good old deterministic testing (dumb robots) is the best way to keep in check LLMs (smart robots) at volume."

### Split by Tool

| Category | Rubrics | Tool |
|----------|---------|------|
| Vale-only | Format Integrity, Deterministic Instructions, Terminology Strictness, Token Efficiency | Fast, deterministic, CI-friendly |
| Vale + LLM | Semantic Headings, Configuration Precision, Security Boundaries | Vale flags, LLM suggests fixes |
| LLM-only | Contextual Independence, Code Executability, Execution Verification | Semantic understanding required |

### Pipeline

```
┌─────────────────────────────────────────────────────────────┐
│ Stage 1: Vale (deterministic, fast, free)                   │
│ - Runs in CI on every commit                                │
│ - Catches 40% of issues instantly                           │
│ - No LLM cost for clean docs                                │
└─────────────────────┬───────────────────────────────────────┘
                      │ only if Vale passes
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 2: LLM Triage (cheap model)                           │
│ - Evaluates 3 semantic rubrics                              │
│ - Identifies which need patches                             │
└─────────────────────┬───────────────────────────────────────┘
                      │ only if issues found
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 3: LLM Specialists (capable model)                    │
│ - One agent per failed rubric                               │
│ - Generates patches                                         │
└─────────────────────────────────────────────────────────────┘
```

### Why This Works
- Vale is battle-tested, fast, CI-native
- LLM only fires when needed (adaptive cost)
- Deterministic rules catch predictable issues
- LLM handles semantic/contextual issues

---

## Vale Rules Needed

### Format Integrity
- Existence: code blocks without language tags
- Regex for unclosed fences

### Deterministic Instructions
- Existence: hedging words ("might", "may want to", "consider", "you could")

### Terminology Strictness
- Consistency: flag term variations

### Token Efficiency
- Existence: filler phrases ("In this section we will...", "As you may know...")

### Semantic Headings (partial)
- Existence: banned headings ("Overview", "Introduction", "Getting Started")

### Configuration Precision (partial)
- Existence: vague versions ("Python 3.x", "recent version")

### Security Boundaries (partial)
- Existence: hardcoded API key patterns

---

## NEXT STEPS

1. Create Vale style for doc-review rubrics
2. Test Vale on sample docs
3. Design LLM prompts for semantic rubrics only
4. Wire into orch or standalone

status: closed


title: Compare BOUNDARIES.md with upstream

depends_on_id: skills-ebh

type: discovered-from

created_by: daemon


title: Create orch skill for multi-model consensus

description: Build a skill that exposes orch CLI capabilities to agents for querying multiple AI models

issue_type: feature


title: Add README.md for web-search skill

description: web-search skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.

type: blocks


title: RFC: .skills manifest pattern for per-repo skill deployment

description: Document the .skills file pattern where projects declare skills in a manifest, .envrc reads it, and agents can query/edit it.


title: Fix ai-skills.nix missing sha256 hash

description: modules/ai-skills.nix:16 has empty sha256 placeholder for opencode-skills npm package. Either get actual hash or remove/comment out the incomplete fetchFromNpm approach.

issue_type: bug


title: spec-review: Expand NFR checklist in prompts

description:
Current prompts mention 'performance, security, accessibility' but miss many critical NFRs.

Expand to include:
- Security (authn/authz, secrets, threat model)
- Privacy/compliance (GDPR, PII)
- Observability (logging, metrics, tracing)
- Reliability (SLOs, failure modes)
- Rollout/rollback strategy
- Migration/backfill
- Data retention/lifecycle
- Cost constraints


title: Decide on screenshot-latest skill deployment

description: DEPLOYED.md shows screenshot-latest as 'Not yet deployed - Pending decision'. Low risk skill that finds existing files. Need to decide whether to deploy or archive.


title: Design graph-based doc discovery

description:
How does doc-review find and traverse documentation?

Approach: Start from README.md or AGENTS.md, graph out from there.

Design questions:
- Parse markdown links to find related docs?
- Follow only relative links or also section references?
- How to handle circular references?
- Depth limit or exhaustive traversal?
- What about orphan docs not linked from root?
- How to represent the graph for chunking decisions?

Considerations:
- Large repos may have hundreds of markdown files
- Not all .md files are "documentation" (changelogs, templates, etc.)
- Some docs are generated and shouldn't be patched

Deliverable: Algorithm/pseudocode for doc discovery + chunking strategy.


title: spec-review: Add Prerequisites section documenting dependencies

description:
SKILL.md and process docs assume orch is installed, prompt files exist, models are available, but none of this is documented.

Add:
- orch install instructions/link
- Required env vars and model availability
- Prompt file locations
- Expected repo structure (specs/ convention)
- Troubleshooting section for common failures


title: Replace SKILL.md with upstream version

description: Upstream has 644 lines vs our 122. Missing: self-test questions, notes quality checks, token checkpointing, database selection, field usage table, lifecycle workflow, common patterns, troubleshooting


title: spec-review: Add context/assumptions step to prompts

description:
Reviews can become speculative without establishing context first.

Add to prompts:
- List assumptions being made
- Distinguish: missing from doc vs implied vs out of scope
- Ask clarifying questions if critical context missing


title: spec-review: Add severity labeling to prompts and reviews

description:
Reviews produce flat lists mixing blockers with minor nits. Hard to make decisions.

Add to prompts:
- Require severity labels: Blocker / High / Medium / Low
- Sort output by severity
- Include impact and likelihood for each issue


title: Compare STATIC_DATA.md with upstream


title: Set up bd-issue-tracking Claude Code skill from beads repo

description:
Install the beads Claude Code skill from https://github.com/steveyegge/beads/tree/main/examples/claude-code-skill

This skill teaches Claude how to effectively use beads for issue tracking across multi-session coding workflows. It provides strategic guidance on when/how to use beads, not just command syntax.

Files to install to ~/.claude/skills/bd-issue-tracking/:
- SKILL.md - Core workflow patterns and decision criteria
- BOUNDARIES.md - When to use beads vs markdown alternatives
- CLI_REFERENCE.md - Complete command documentation
- DEPENDENCIES.md - Relationship types and patterns
- WORKFLOWS.md - Step-by-step procedures
- ISSUE_CREATION.md - Quality guidelines
- RESUMABILITY.md - Making work resumable across sessions
- STATIC_DATA.md - Using beads as reference databases

Can symlink or copy the files. Restart Claude Code after install.


title: Compare CLI_REFERENCE.md with upstream


title: spec-review: Add spike/research task handling

description:
Tasks like 'Investigate X' can linger without clear outcomes.

Add to REVIEW_TASKS:
- Flag research/spike tasks
- Require timebox and concrete outputs (decision record, prototype, risks)
- Pattern for handling unknowns


title: spec-review: Add traceability requirements across artifacts

description:
Prompts don't enforce spec → plan → tasks linkage. Drift can occur without detection.

Add:
- Require trace matrix or linkage in reviews
- Each plan item should reference spec requirement
- Each task should reference plan item
- Flag unmapped items and extra scope


title: Update main README to list all 9 skills

description: Main README.md 'Skills Included' section only lists worklog and update-spec-kit. Repo actually has 9 skills: template, worklog, update-spec-kit, screenshot-latest, niri-window-capture, tufte-press, update-opencode, web-research, web-search.


title: Consider repo-setup-verification skill

description:
The dotfiles repo has a repo-setup-prompt.md verification checklist that could become a skill.

**Source**: ~/proj/dotfiles/docs/repo-setup-prompt.md

**What it does**:
- Verifies .envrc has use_api_keys and skills loading
- Checks .skills manifest exists with appropriate skills
- Optionally checks beads setup
- Verifies API keys are loaded

**As a skill it could**:
- Be invoked to audit any repo's agent setup
- Offer to fix missing pieces
- Provide consistent onboarding for new repos

**Questions**:
- Is this better as a skill vs a slash command?
- Should it auto-fix or just report?
- Does it belong in skills repo or dotfiles?


title: Design doc-review skill

description:
# doc-review skill

Fight documentation drift with a non-interactive review process that generates patchfiles for human review.

## Problem
- No consistent documentation system across repos
- Stale content accumulates
- Structural inconsistencies (docs not optimized for agents)

## Envisioned Workflow

```bash
# Phase 1: Generate patches (non-interactive, use spare credits, test models)
doc-review scan ~/proj/foo --model claude-sonnet --output /tmp/foo-patches/

# Phase 2: Review patches (interactive session)
cd ~/proj/foo
claude  # human reviews patches, applies selectively
```

## Design Decisions Made

- **Trigger**: Manual invocation (not CI). Use case includes burning extra LLM credits, testing models repeatably.
- **Source of truth**: Style guide embedded in prompt template. Blessed defaults, overridable per-repo.
- **Output**: Patchfiles for human review in interactive Claude session.
- **Chunking**: Based on absolute size, not file count. Logical chunks easy for Claude to review.
- **Scope detection**: Graph-based discovery starting from README.md or AGENTS.md, not glob-all-markdown.

## Open Design Work

### Agent-Friendly Doc Conventions (needs brainstorming)
What makes docs agent-readable?
- Explicit context (no "as mentioned above")
- Clear section headers for navigation
- Self-contained sections
- Consistent terminology
- Front-loaded summaries
- ???

### Prompt Content
Full design round needed on:
- What conventions to enforce
- How to express them in prompt
- Examples of "good" vs "bad"

### Graph-Based Discovery
How does traversal work?
- Parse links from README/AGENTS.md?
- Follow relative markdown links?
- Depth limit?

## Skill Structure (tentative)
```
skills/doc-review/
├── prompt.md           # Core review instructions + style guide
├── scan.sh             # Orchestrates: find docs → invoke claude → emit patches
└── README.md
```

## Out of Scope (for now)
- Cross-repo standardization (broader than skills repo)
- CI integration
- Auto-apply without human review

issue_id: skills-bcu


title: spec-review: Add Definition of Ready checklists for each phase

description:
'Ready for /speckit.plan' and similar are underspecified.

Add concrete checklists:
- Spec ready for planning: problem statement, goals, constraints, acceptance criteria, etc.
- Plan ready for tasks: milestones, risks, dependencies, test strategy, etc.
- Tasks ready for bd: each task has acceptance criteria, dependencies explicit, etc.


title: spec-review: Add anti-hallucination constraints to prompts

description:
Models may paraphrase and present as quotes, or invent requirements/risks not in the doc.

Add:
- 'Quotes must be verbatim'
- 'Do not assume technologies/constraints not stated'
- 'If missing info, list as open questions rather than speculating'


title: Create spec-review skill for orch + spec-kit integration

description:
A new skill that integrates orch multi-model consensus with spec-kit workflows.

**Purpose**: Use different models/temps/stances to review spec-kit artifacts before phase transitions.

**Proposed commands**:
- /spec-review.spec - Critique current spec for completeness, ambiguity, gaps
- /spec-review.plan - Evaluate architecture decisions in plan
- /spec-review.gate - Go/no-go consensus before phase transition

**Structure**:
```
skills/spec-review/
├── SKILL.md
├── commands/
│   ├── spec.md
│   ├── plan.md
│   └── gate.md
└── prompts/
    └── ...
```

**Key design points**:
- Finds spec/plan files from current branch or specs/ directory
- Invokes orch with appropriate prompt, models, stances
- Presents consensus/critique results
- AI reviewing AI is valuable redundancy (different models/temps/stances)

**Dependencies**:
- orch CLI must be available (blocked on dotfiles-3to)
- spec-kit project structure conventions


title: Add direnv helper for per-repo skill deployment

description: Create sourceable helper script and documentation for the standard per-repo skill deployment pattern using direnv + nix build.


title: Research OpenCode agents for skill integration

description: DEPLOYMENT.md:218 has TODO to research OpenCode agents. Need to understand how Build/Plan/custom agents work and whether skills need agent-specific handling.


title: Design: orch as local agent framework

description:
# Orch Evolution: From Consensus Tool to Agent Framework

## Current State
- `orch consensus` - multi-model queries
- `orch chat` - single model queries
- No state, no pipelines, no retries

## Proposed Extensions

### Pipeline Mode
```bash
orch pipeline config.yaml
```
Where config.yaml defines:
- Stages (triage → specialists → verify)
- Routing logic (if triage finds X, run specialist Y)
- Retry policy

### Evaluate Mode (doc-review specific)
```bash
orch evaluate doc.md --rubrics=1,4,7 --output=patches/
```
- Applies specific rubrics to document
- Outputs JSON or patches

### Parallel Mode
```bash
orch parallel --fan-out=5 --template="evaluate {rubric}" rubrics.txt
```
- Fan-out to multiple parallel calls
- Aggregate results

## Open Questions
1. Does this belong in orch or a separate tool?
2. Should orch pipelines be YAML-defined or code-defined?
3. How does this relate to Claude Code Task subagents?
4. What's the minimal viable extension?

## Context
Emerged from doc-review skill design - need multi-pass evaluation but don't want to adopt heavy framework (LangGraph, etc.)


title: orch skill is documentation-only, needs working invocation mechanism

description:
The orch skill provides SKILL.md documentation but no working invocation mechanism.

**Resolution**: Install orch globally via home-manager (dotfiles-3to). The skill documents a system tool, doesn't need to bundle it.

**Blocked by**: dotfiles-3to (Add orch CLI to home-manager packages)


title: orch: add command to show available/configured models

description:
## Problem

When trying to use orch, you have to trial-and-error through models to find which ones have API keys configured. Each failure looks like:

```
Error: GEMINI_API_KEY not set. Required for Google Gemini models.
```

No way to know upfront which models are usable.

## Proposed Solution

Add `orch models` or `orch status` command:

```bash
$ orch models
Available models:
  ✓ flash      (GEMINI_API_KEY set)
  ✓ gemini     (GEMINI_API_KEY set)
  ✗ deepseek   (OPENROUTER_KEY not set)
  ✗ qwen       (OPENROUTER_KEY not set)
  ✓ gpt        (OPENAI_API_KEY set)
```

Or at minimum, on failure suggest alternatives:
```
Error: GEMINI_API_KEY not set. Try --model gpt or --model deepseek instead.
```

## Context

Hit this while trying to brainstorm with high-temp gemini - had to try 4 models before realizing none were configured in this environment.


title: Compare bd-issue-tracking skill files with upstream

description: Fetch upstream beads skill files and compare with our condensed versions to identify differences


title: Compare WORKFLOWS.md with upstream


title: use-skills.sh: stderr from nix build corrupts symlinks when repo is dirty

description:
In use-skills.sh, the line:

```bash
out=$(nix build --print-out-paths --no-link "${SKILLS_REPO}#${skill}" 2>&1) || {
```

The `2>&1` merges stderr into stdout. When the skills repo is dirty, nix emits a warning to stderr which gets captured into $out and used as the symlink target.

Result: symlinks like:
```
orch -> warning: Git tree '/home/dan/proj/skills' is dirty
/nix/store/j952hgxixifscafb42vmw9vgdphi1djs-ai-skill-orch
```

Fix: redirect stderr to /dev/null or filter it out before creating symlink.


title: spec-review: File discovery is brittle, can pick wrong file silently

description:
The fallback `find ... | head -1` is non-deterministic and can select wrong spec/plan/tasks file without user noticing. Branch names with `/` also break path construction.

Fixes:
- Fail fast if expected file missing
- Print chosen file path before proceeding
- Require explicit confirmation if falling back
- Handle branch names with slashes


title: spec-review: Balance negativity bias in prompts

description:
'Be critical' and 'devil's advocate' can bias toward over-flagging without acknowledging what's good.

Add:
- 'List top 3 strongest parts of the document'
- 'Call out where document is sufficiently clear/testable'
- Categorize :against concerns as confirmed/plausible/rejected


title: Orch skill: document or handle orch not in PATH

description: Skill docs show 'orch consensus' but orch requires 'uv run' from ~/proj/orch. Either update skill to invoke correctly or document installation requirement.


title: Compare DEPENDENCIES.md with upstream

issue_id: skills-lie


title: Compare ISSUE_CREATION.md with upstream

issue_id: skills-lvg


title: Apply niri-window-capture code review recommendations

description: CODE-REVIEW-niri-window-capture.md identifies action items: add dependency checks to scripts, improve error handling for niri failures, add screenshot directory validation, implement rate limiting. See High/Medium priority sections.


title: spec-review: Define consensus thresholds and decision rules

description:
'Use judgment' for mixed results leads to inconsistent decisions.

Define:
- What constitutes consensus (2/3? unanimous?)
- How to handle NEUTRAL votes
- Tie-break rules
- When human override is acceptable and how to document it


title: Clean up stale beads.left.jsonl merge artifact

description: bd doctor flagged multiple JSONL files. beads.left.jsonl is empty merge artifact that should be removed: git rm .beads/beads.left.jsonl


title: Add README.md for web-research skill

description: web-research skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.

issue_id: skills-qeh


title: Compare RESUMABILITY.md with upstream


title: Resolve web search design questions

description: web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.


title: Investigate hooks for parallel orch queries

description: When using orch skill, it would be useful to spin off multiple model queries in parallel automatically (e.g., gemini + gpt simultaneously). Explore if Claude Code hooks can trigger parallel background processes when the orch skill is invoked.