From 1f227a3d91b222e1e0a48fc7519a952c4c6863ff Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 20:53:29 +0200 Subject: [PATCH 1/4] chore: remove /inbox and /implement-feature commands /inbox duplicated /triage's idea capture, and /implement-feature was an interim AFK runner being replaced by unic-dlc-build (see ADR-0031). - Delete .claude/commands/inbox.md, .claude/skills/implement-feature/, and docs/inbox/README.md - Add ADR-0031 superseding ADR-0027 and ADR-0029 - Update AGENTS.md, CONTRIBUTING.md, and the process/agents docs to describe the current state (manual /tdd, unic-dlc-build as the long-term Feature Runner) The 10 captured ideas under docs/inbox/ are kept as historical artifacts; docs/issues/feature-runner/PRD.md is left untouched (already closed). Co-Authored-By: Claude Opus 4.7 --- .claude/commands/inbox.md | 66 ------ .claude/skills/implement-feature/SKILL.md | 189 ------------------ .../references/runner-output-formats.md | 106 ---------- .../references/tdd-prompt-template.md | 27 --- AGENTS.md | 5 - CONTRIBUTING.md | 6 +- .../adr/0027-feature-runner-context-bundle.md | 2 +- .../adr/0029-feature-runner-afk-invocation.md | 2 +- .../0031-retire-implement-feature-skill.md | 27 +++ docs/agents/feature-runner.md | 131 ++---------- docs/inbox/README.md | 43 ---- docs/process/ai-development.md | 94 +++------ docs/process/development-workflow.md | 54 ++--- 13 files changed, 93 insertions(+), 659 deletions(-) delete mode 100644 .claude/commands/inbox.md delete mode 100644 .claude/skills/implement-feature/SKILL.md delete mode 100644 .claude/skills/implement-feature/references/runner-output-formats.md delete mode 100644 .claude/skills/implement-feature/references/tdd-prompt-template.md create mode 100644 docs/adr/0031-retire-implement-feature-skill.md delete mode 100644 docs/inbox/README.md diff --git a/.claude/commands/inbox.md b/.claude/commands/inbox.md deleted file mode 100644 index 9b0d9608..00000000 --- a/.claude/commands/inbox.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -allowed-tools: [Write, Bash] -argument-hint: '' -description: 'Capture a raw idea into docs/inbox/ without interrupting the current conversation' ---- - -# Inbox capture - -**Arguments:** "$ARGUMENTS" - -Capture the idea in `$ARGUMENTS` as a file in `docs/inbox/`. Act immediately — no follow-up -questions. - -## Step 1 — Generate a slug - -From the idea text: - -1. Lowercase everything -2. Replace spaces and punctuation with hyphens -3. Collapse multiple hyphens into one -4. Strip leading/trailing hyphens -5. Truncate to 50 characters at a word boundary - -Examples: - -- `"pr-review should support GitLab!"` → `pr-review-should-support-gitlab` -- `"add dark mode support to the dashboard component"` → `add-dark-mode-support-to-the-dashboard-component` -- `"implement user authentication with OAuth2 and role-based access control"` → `implement-user-authentication-with-oauth2-and` (truncated at word boundary before 50 chars) - -## Step 2 — Check for collisions - -```bash -node -e " - const root = require('child_process').execSync('git rev-parse --show-toplevel').toString().trim(); - const p = require('path').join(root, 'docs', 'inbox', '.md'); - process.exit(require('fs').existsSync(p) ? 1 : 0); -" -``` - -If the file exists, append `-2` (then `-3`, etc.) until the path is free. - -## Step 3 — Write the file - -Resolve the repo root with `git rev-parse --show-toplevel`, then create `/docs/inbox/.md`: - -```markdown ---- -title: -created: ---- - - -``` - -Use the `Write` tool. Do not create any other files. - -## Step 4 — Confirm - -Reply with exactly one line: - -```txt -Captured → docs/inbox/.md -``` - -Nothing else. No summary, no next steps, no follow-up questions. The user is in the middle -of something else. diff --git a/.claude/skills/implement-feature/SKILL.md b/.claude/skills/implement-feature/SKILL.md deleted file mode 100644 index 28ef8ab3..00000000 --- a/.claude/skills/implement-feature/SKILL.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -name: implement-feature -argument-hint: '[slug]' -description: This skill should be used when the user asks to "implement a feature", "run the Feature Runner", "/implement-feature", "implement all issues for ", or "drain the issue queue overnight". Automates the implementation side of the AI-development cycle for one Feature: creates an isolated worktree and branch, runs /tdd on every ready-for-agent issue in dependency order, and opens a PR when done. ---- - -# Implement Feature - -Automate the implementation side of the AI-development cycle for one Feature. Takes a slug, creates an isolated branch, runs `/tdd` on every `ready-for-agent` issue in dependency order, and marks each `resolved` on success. - -**Invocation:** `/implement-feature [slug]` - -## Quick start - -- **Named run** — `/implement-feature pr-review-doc-context-enrichment` — targets a specific Feature slug directly; creates a worktree, runs all `ready-for-agent` issues, opens a PR. -- **Auto-select** — `/implement-feature` with no argument — scans `docs/issues/` and picks the first Feature alphabetically that has at least one `ready-for-agent` issue and no unprepped issues (`needs-triage`, `needs-info`, `needs-specs`). Picks up partial features after a failure fix automatically. -- **Overnight loop** — `/loop /implement-feature` — drains the queue unattended; the runner emits `LOOP_COMPLETE` when no qualifying Feature remains, which terminates the loop. -- **Safe to interrupt** — Ctrl+C during any issue leaves that issue at `ready-for-agent`; re-running resumes from the first unresolved issue. Note: a **/tdd failure** (as opposed to a Ctrl+C interrupt) sets the failing issue to `needs-info`, preventing auto-select from retrying until the developer intervenes. - -## Steps - -### 0. Resolve the slug - -**If a slug argument was provided**, use it directly and proceed to step 1. - -**If no argument was provided**, scan `docs/issues/` for qualifying features: - -1. Use the Bash tool to list immediate subdirectories of `docs/issues/`: - -``` -ls -d docs/issues/*/ -``` - -2. For each subdirectory (potential feature slug), use the Bash tool to list its `NN-*.md` files and use the Read tool to check the `**Status:**` line of each one. A feature **qualifies** if: - - - At least one `NN-*.md` file has status `ready-for-agent`, **and** - - Every `NN-*.md` file has a status in `{ready-for-agent, resolved, closed, rejected, ready-for-human}`. - - Any file with status `needs-triage`, `needs-info`, `needs-specs`, or any unrecognised state **disqualifies the whole feature** — it is not fully prepped for autonomous execution. Features where every file is `resolved`, `closed`, or `rejected` (nothing left to run) are also skipped. - -3. Sort the qualifying slugs alphabetically and select the first one. - -4. **If no qualifying feature exists**, emit the **LOOP_COMPLETE signal** (see `references/runner-output-formats.md`) on its own line and exit cleanly (no error). Do not output anything after it. - -5. **If a qualifying feature was found**, set the slug to that feature's directory name and continue to step 1. - -### 1. Resolve the feature directory and assemble the static context bundle - -The slug argument maps directly to `docs/issues//`. Use the Bash tool to confirm: - -1. The directory exists (e.g. `ls docs/issues//`). -2. It contains at least one `NN-*.md` file (e.g. `ls docs/issues//[0-9]*.md`). -3. At least one of those files has `**Status:** ready-for-agent` (use the Read tool on each file and inspect the `**Status:**` line). - -If any of these checks fails, stop and report the specific reason to the user. Do not create a worktree. - -**Read the PRD:** `docs/issues//PRD.md`. Scan its content for references matching `apps/claude-code//` (any path that starts with that prefix). This determines the ADR scope: - -- **Plugin feature** — one or more `apps/claude-code//` references found → use that plugin's `apps/claude-code//CONTEXT.md` and `apps/claude-code//docs/adr/`. Do **not** also inject root ADRs. -- **Repo/tooling feature** — no such references found → use root `CONTEXT.md` and root `docs/adr/`. - -Also extract the `title:` field from the PRD's YAML frontmatter (the value between the opening `---` and closing `---` at the top of the file). Retain it for use in step 7's PR title derivation. - -**Read the scoped CONTEXT.md** using the Read tool. - -**Read all ADR files** in the scoped ADR directory: list `*.md` files using the Bash tool, then read each one using the Read tool. - -**Get the last 5 git commits** using the Bash tool: - -``` -git log --oneline -5 -``` - -These items (PRD content + title, CONTEXT.md, ADRs, recent commits) are static — gather them once before the issue loop begins. - -### 2. Create the worktree and branch - -First, check whether a worktree from a prior run already exists using the Bash tool: - -``` -ls .claude/worktrees/ -``` - -- **Exists** — reuse it. The branch `feature/afk/` already contains the committed work from the previous run. Skip `git worktree add`. -- **Does not exist** — create it using the Bash tool: - -``` -git worktree add .claude/worktrees/ -b feature/afk/ develop -``` - -The worktree lands at `.claude/worktrees/`. All subsequent implementation work happens inside that worktree. - -### 3. Collect issues, build the dependency graph, and derive execution order - -Use the Bash tool to list **all** `NN-*.md` files in `docs/issues//` (including `resolved` and `closed` — they are needed for graph completeness): - -``` -ls docs/issues//[0-9]*.md -``` - -Use the Read tool to read each file. For every file record: - -- Its **numeric prefix** (the `NN` integer from the filename). -- Its **status** (`**Status:**` line). -- Its **`## Blocked by`** list — the filenames or paths referenced there. `## Blocked by: None`, `## Blocked by: None — can start immediately`, or a missing `## Blocked by` section all mean no predecessors. - -**Missing-blocker check — halt before executing anything if violated:** - -For each `## Blocked by` reference, verify the referenced filename actually exists in `docs/issues//`. If a referenced blocker file is missing (typo, renamed, deleted), halt immediately with the **missing blocker error** (see `references/runner-output-formats.md`), naming the issue and the unresolvable reference. Do not silently treat it as satisfied. - -**Conflict check — halt before executing anything if violated:** - -For each issue A that lists issue B in `## Blocked by`: if B's numeric prefix is greater than A's numeric prefix, the dependency contradicts numerical convention. Halt immediately with the **dependency conflict error** (see `references/runner-output-formats.md`), naming both issues. - -**Build the execution queue:** - -From the dependency graph, compute a topological order over all issues (using `## Blocked by` edges). Filter the topological sequence to only `ready-for-agent` issues — `resolved`, `closed`, and `rejected` issues are satisfied and act as satisfied dependency nodes, not as items to execute. - -**Unsatisfied dependency check — halt before executing anything if violated:** - -For each `ready-for-agent` issue in the execution queue, inspect its `## Blocked by` list. If any listed blocker has status `ready-for-human`, halt immediately with the **unsatisfied dependency error** (see `references/runner-output-formats.md`), naming both issues. - -This ordered list is the execution queue. Record M = number of items in the queue (frozen at this moment — do not recount mid-run). - -### 4. Implement each issue via `/tdd` - -For each issue file in queue order (N = 1, 2, … M), before invoking `/tdd`, emit the **progress line** (see `references/runner-output-formats.md`) substituting N, M, and the issue title (first `# Heading` line of the issue file). - -Invoke the sub-agent using the Agent tool with `subagent_type: general-purpose` — the only stock type with access to both the Skill tool (to load `/tdd`) and the Edit/Write tools (to write code). The issue's `## Acceptance criteria` replaces the interactive planning phase — pass it as the pre-approved plan so the agent skips confirmation and proceeds directly to implementation. - -Before constructing the prompt, use the Read tool to read all sibling issue files (`docs/issues//[0-9]*.md` except the current issue) at their current state — this gives the sub-agent visibility into what is already resolved and what is still pending. - -Construct the prompt using the template in `references/tdd-prompt-template.md`, substituting all `` values at runtime. Pass the constructed prompt to the Agent tool. Wait for the agent to return before continuing. - -**On failure:** If the Agent call signals failure (throws, returns an error, or explicitly reports it could not complete the issue): - -1. Using the Edit tool, change the `**Status:** ready-for-agent` line to `**Status:** needs-info`. This prevents auto-select from picking up this Feature on subsequent loop iterations. - -2. Append the **failure note** (see `references/runner-output-formats.md`) to the issue file using the Edit tool, substituting ``. - -3. Stop the runner immediately. Do not execute any subsequent issues — they may depend on a foundation this issue was meant to lay. - -4. Report to the user: which issue failed, that the worktree is at `.claude/worktrees/` on branch `feature/afk/`, and that no subsequent issues were run. - -### 5. Mark each issue resolved - -After the Agent call for an issue returns **successfully**, update the issue file using the Edit tool: change the `**Status:** ready-for-agent` line to `**Status:** resolved`. - -### 6. Continue until queue is empty - -Repeat steps 4–5 for every issue in the queue. When the last issue is resolved, proceed to step 7. - -### 7. Open a pull request and clean up - -**Push the branch:** - -``` -git -C .claude/worktrees/ push -u origin feature/afk/ -``` - -**Derive the PR title** from the PRD's `title` frontmatter field (already read in step 1) and the slug: - -``` -feat(): -``` - -**List the resolved issues** — all `NN-*.md` files in `docs/issues//` whose status is now `resolved` (every issue the runner just processed, in numerical order). - -**Open the PR** using the Bash tool. The exact `gh pr create` invocation with the heredoc-wrapped body lives in `references/runner-output-formats.md` under "PR body template" — use that form verbatim, substituting ``, ``, and the resolved-issue list before running it. Run from inside the worktree (`git -C .claude/worktrees/`) or pass `--repo` if needed. **Do not run the snippet without substitution** — angle-bracket placeholders are not valid shell. - -**Failure handling for steps 7a and 7b:** If `git push` or `gh pr create` fails (non-zero exit, network error, permission denied, branch protection, etc.): - -1. Stop immediately. Do **not** remove the worktree. -2. Report to the user: which command failed, the error output, that the worktree is at `.claude/worktrees/` on branch `feature/afk/`, and that all issues are still `resolved` (the failure is post-implementation). -3. Suggest re-running `git push` / `gh pr create` manually once the cause is resolved. - -**Remove the worktree** only after the PR is opened successfully (PR URL returned by `gh`): - -``` -git worktree remove .claude/worktrees/ -``` - -Report the PR URL and the list of resolved issues to the user. - -## Supporting Documentation - -- **`references/runner-output-formats.md`** — verbatim strings for the progress line, dependency conflict error, unsatisfied dependency error, failure note, PR body template, and `LOOP_COMPLETE` signal. -- **`references/tdd-prompt-template.md`** — the AFK prompt template passed to the Agent tool for each `/tdd` sub-agent invocation; substitute all `` values at runtime. -- **`docs/agents/feature-runner.md`** — human-facing reference: lifecycle diagram, dependency-satisfaction matrix, ADR scope, historical cleanup convention. Maintained in parallel; consult for broader context, not for runtime instructions. diff --git a/.claude/skills/implement-feature/references/runner-output-formats.md b/.claude/skills/implement-feature/references/runner-output-formats.md deleted file mode 100644 index 23ae43fd..00000000 --- a/.claude/skills/implement-feature/references/runner-output-formats.md +++ /dev/null @@ -1,106 +0,0 @@ -# Runner output formats - -Verbatim strings emitted or embedded by the Feature Runner. `SKILL.md` references this file by name rather than repeating these strings inline. - ---- - -## Progress line - -Emitted to the user before each `/tdd` invocation. - -``` -Implementing issue N of M: -``` - ---- - -## Missing blocker error - -Emitted when a `## Blocked by` reference points to a filename that does not exist in `docs/issues//`. The runner halts before executing any issue. - -``` -Feature Runner error: missing blocker reference. - Issue NN- lists "" in ## Blocked by, but that file does not exist in docs/issues//. - Check for a typo, a rename, or a deleted issue. Resolve the reference manually before re-running. -``` - ---- - -## Dependency conflict error - -Emitted when a `## Blocked by` reference points to an issue with a higher numeric prefix than the issue being blocked. The runner halts before executing any issue. - -``` -Feature Runner error: dependency conflict detected. - Issue NN- is blocked by NN-, but NN- has a higher number than NN-. - This conflicts with the numerical ordering convention. Resolve the ordering manually before re-running. -``` - ---- - -## Unsatisfied dependency error - -Emitted when a `ready-for-agent` issue in the execution queue has a `## Blocked by` dependency whose status is `ready-for-human`. The runner halts before executing any issue. - -``` -Feature Runner error: unsatisfied dependency. - Issue NN- is blocked by NN-, but NN- has status ready-for-human. - Complete issue NN- manually (or update its status) before re-running /implement-feature . -``` - ---- - -## Failure note - -Appended to a failing issue file under `## Comments` when `/tdd` cannot complete an issue. The `**Status:**` line is also changed to `needs-info` (see SKILL.md step 4). - -```markdown -## Comments - -> _This was generated by AI during triage._ - -**Feature Runner failure** — `/tdd` could not complete this issue. Status has been set to `needs-info`. - -The worktree at `.claude/worktrees/` has been left in place for inspection. Once the issue is resolved manually, restore `**Status:** ready-for-agent` and re-run `/implement-feature ` to resume. Alternatively, close or reject the issue if it should not be retried. -``` - ---- - -## PR body template - -The body passed to `gh pr create` after all issues in a feature are resolved. - -```markdown -## Feature - -`docs/issues//PRD.md` - -## Resolved issues - -- `docs/issues//NN-.md` -- ... - -🤖 Implemented by the Feature Runner via `/implement-feature ` -``` - -Pass via a bash heredoc: - -``` -gh pr create \ - --base develop \ - --title "feat(): " \ - --body "$(cat <<'EOF' - -EOF -)" -``` - ---- - -## LOOP_COMPLETE signal - -Emitted on its own line when no qualifying feature exists during auto-selection. Must appear alone — nothing before or after it on the same line. This is the stop signal that `/loop /implement-feature` uses to terminate an overnight draining run. - -``` -LOOP_COMPLETE -``` diff --git a/.claude/skills/implement-feature/references/tdd-prompt-template.md b/.claude/skills/implement-feature/references/tdd-prompt-template.md deleted file mode 100644 index ff4a8d9d..00000000 --- a/.claude/skills/implement-feature/references/tdd-prompt-template.md +++ /dev/null @@ -1,27 +0,0 @@ -# /tdd AFK prompt template - -Passed to the Agent tool for each `/tdd` sub-agent invocation. All `` values are substituted at runtime before the prompt is sent. - -``` -You are running `/tdd` in AFK mode. The interactive planning phase is complete — do not ask for confirmation. Begin by invoking the `tdd` skill via the Skill tool to load its full procedural guidance (red→green→refactor, vertical-slice rule, deep-modules / interface-design / refactoring sub-references), then follow it using the acceptance criteria below as the pre-approved plan and proceed directly to the red→green→refactor loop. - -Working directory: .claude/worktrees/ - ---- ISSUE --- - - ---- PRD (parent context) --- - - ---- SIBLING ISSUES --- - - ---- CONTEXT.md --- - - ---- ADRs --- - - ---- RECENT COMMITS (last 5) --- - -``` diff --git a/AGENTS.md b/AGENTS.md index 5fdb77eb..a3f0e63b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,6 @@ packages/ docs/ ├── adr/ # Architectural Decision Records ├── agents/ # Agent skill documentation -├── inbox/ # Raw ideas pending triage ├── issues/ # Grilled and scoped feature issues ├── plans/ # Retired spec files (historical) ├── process/ # Process and workflow guides @@ -140,10 +139,6 @@ Issues live in GitHub Issues at `unic/unic-agents-plugins` (planned migration to Multi-context repo: Per-plugin `CONTEXT.md` files live under `apps/claude-code//`. Root `CONTEXT-MAP.md` at repo root. See `docs/agents/domain.md`. -### Inbox - -Raw ideas, bugs, and stray thoughts that haven't been grilled or scoped yet live in `docs/inbox/`. Use `/inbox ` to capture without interrupting the current flow. Items graduate to `docs/issues//` after grilling. See `docs/inbox/README.md`. - ## Agent skills diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cf33180..6619fa42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ This monorepo uses a Feature-driven development workflow. For the full lifecycle — from idea capture through grilling, PRD, issues, execution, and QA — see **[`docs/process/development-workflow.md`](docs/process/development-workflow.md)**. -New features and fixes are tracked as Features in the issue tracker under `docs/issues//`. Implementation is driven by the **Feature Runner** (`/implement-feature`) or done manually using `/tdd` for individual issues. +New features and fixes are tracked as Features in the issue tracker under `docs/issues//`. Implementation is done manually using `/tdd` for individual issues; the **Feature Runner** (`unic-dlc-build`, shipped by `unic-archon-dlc`) is the long-term AFK runner once it is wired into this repo (see [ADR-0030](docs/adr/0030-retire-ralph-adopt-archon-runner.md)). ## Cross-cutting standards @@ -72,10 +72,10 @@ pnpm install All work enters through the issue tracker as a Feature. The recommended flow: -1. Capture the idea with `/inbox ` or open a GitHub Issue directly. +1. Capture the idea — open a GitHub Issue directly, or run `/triage` to walk it through the state machine. 2. Grill the design with `/grill-me` or `/grill-with-docs` until the problem and solution are clear. 3. Create a PRD and issues with `/to-prd` → `/to-issues`. -4. Implement: `/implement-feature ` for automated AFK execution, or `/tdd` manually for individual issues. +4. Implement each issue manually with `/tdd`. (AFK execution via `unic-dlc-build` will replace this step once the harness is wired in — see [ADR-0030](docs/adr/0030-retire-ralph-adopt-archon-runner.md) and [ADR-0031](docs/adr/0031-retire-implement-feature-skill.md).) 5. Open a PR targeting `develop`. See [`docs/process/development-workflow.md`](docs/process/development-workflow.md) for the full 8-phase lifecycle. diff --git a/docs/adr/0027-feature-runner-context-bundle.md b/docs/adr/0027-feature-runner-context-bundle.md index 79366449..29bdf42f 100644 --- a/docs/adr/0027-feature-runner-context-bundle.md +++ b/docs/adr/0027-feature-runner-context-bundle.md @@ -1,6 +1,6 @@ # 0027. Feature Runner injects a scoped context bundle into every `/tdd` sub-agent invocation -**Status:** Accepted (2026-05) +**Status:** Superseded by [ADR-0031](0031-retire-implement-feature-skill.md) (2026-05) ## Context diff --git a/docs/adr/0029-feature-runner-afk-invocation.md b/docs/adr/0029-feature-runner-afk-invocation.md index 59e12d64..33a54392 100644 --- a/docs/adr/0029-feature-runner-afk-invocation.md +++ b/docs/adr/0029-feature-runner-afk-invocation.md @@ -1,6 +1,6 @@ # 0029. Feature Runner invokes `/tdd` non-interactively; issue acceptance criteria replace the planning phase -**Status:** Accepted (2026-05) +**Status:** Superseded by [ADR-0031](0031-retire-implement-feature-skill.md) (2026-05) ## Context diff --git a/docs/adr/0031-retire-implement-feature-skill.md b/docs/adr/0031-retire-implement-feature-skill.md new file mode 100644 index 00000000..5f942785 --- /dev/null +++ b/docs/adr/0031-retire-implement-feature-skill.md @@ -0,0 +1,27 @@ +# 0031. Retire the `/implement-feature` skill; Feature Runner backed solely by `unic-dlc-build` + +**Status:** Accepted (2026-05) + +## Context + +[ADR-0030](0030-retire-ralph-adopt-archon-runner.md) retired `ralph-orchestrator` and declared `unic-dlc-build` (shipped by `unic-archon-dlc`) the long-term Feature Runner. As an interim measure while `unic-dlc-build` matured, a `/implement-feature` Claude Code skill was added at `.claude/skills/implement-feature/`. It assembled a context bundle ([ADR-0027](0027-feature-runner-context-bundle.md)) and invoked `/tdd` as a non-interactive sub-agent for each `ready-for-agent` issue ([ADR-0029](0029-feature-runner-afk-invocation.md)). + +In practice the skill was not adopted: + +1. **Single-purpose duplication** — it replicated, in skill form, exactly what `unic-dlc-build` is built to do. Maintaining two runners doubled the surface for prompt drift and made it unclear which one was canonical. +2. **Agent-tool invocation is fragile** — driving `/tdd` through `Agent` with `subagent_type: general-purpose` cannot match the affordances of a dedicated harness (worktree management, retry semantics, observability). Treating the interim as a real path delayed the move to `unic-dlc-build`. +3. **Capture path conflict** — the companion `/inbox` slash command duplicated `triage`'s capture entry point. Ideas now go straight to the issue tracker (or to `triage`), so the inbox-then-grill staging area is no longer needed. + +## Decision + +- Remove `.claude/skills/implement-feature/` (the skill directory, references, and runner output formats). +- Remove `.claude/commands/inbox.md` and `docs/inbox/README.md`. Existing files under `docs/inbox/` remain as historical artifacts; no new ones are captured there. +- Designate `unic-dlc-build` (via `unic-archon-dlc`) as the **sole** Feature Runner implementation going forward. Until `unic-dlc-build` is wired into this repo, individual issues are implemented manually via `/tdd`, as already stated in ADR-0030. +- [ADR-0027](0027-feature-runner-context-bundle.md) and [ADR-0029](0029-feature-runner-afk-invocation.md) are superseded by this decision. Their context-bundle and AFK-invocation choices described `/implement-feature`'s internals, not portable design constraints; `unic-dlc-build` is free to make its own decisions about both. + +## Consequences + +- `AGENTS.md`, `CONTRIBUTING.md`, `docs/process/ai-development.md`, `docs/process/development-workflow.md`, and `docs/agents/feature-runner.md` are updated to remove references to `/implement-feature` and `/inbox` and to describe the current state (manual `/tdd`, `unic-dlc-build` as the runner). +- The Feature Runner concept (as defined in root `CONTEXT.md`) is unchanged — it remains "the skill that implements a Feature's issues end-to-end in one worktree, branch, and pull request. Backed by `unic-dlc-build`." Only the interim Claude Code skill implementation is removed. +- [ADR-0028](0028-blocked-by-canonical-sequencing.md) is **not** superseded — it defines the canonical sequencing signal (`## Blocked by`) for any Feature Runner implementation, including `unic-dlc-build`. +- Captured ideas under `docs/inbox/*.md` are not migrated automatically. They graduate to issues only when someone triages them. diff --git a/docs/agents/feature-runner.md b/docs/agents/feature-runner.md index da361787..9c141e1a 100644 --- a/docs/agents/feature-runner.md +++ b/docs/agents/feature-runner.md @@ -1,126 +1,23 @@ # Feature Runner -The Feature Runner is the `/implement-feature` skill. It automates the implementation side of the AI-development cycle: given a Feature slug, it creates an isolated branch, works through all `ready-for-agent` issues in dependency order using `/tdd`, opens a pull request, and marks each issue `resolved`. +The **Feature Runner** is the concept of a runner that implements a Feature's issues end-to-end in one worktree, branch, and pull request — see root `CONTEXT.md`. -Invoke it with `/implement-feature ` (named Feature) or `/implement-feature` (auto-select). Compose it with `/loop` for overnight queue draining. +## Current state -## Lifecycle +- **Current default — manual `/tdd` per issue.** Until the AFK runner is wired into this repo, the developer drives `/tdd` against each `ready-for-agent` issue, respects `## Blocked by` order ([ADR-0028](../adr/0028-blocked-by-canonical-sequencing.md)), marks the issue `resolved`, and opens a PR targeting `develop` once the feature's issues are done. +- **Long-term AFK runner — `unic-dlc-build`.** Shipped by `unic-archon-dlc` (also developed in this monorepo). See [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md) for the retirement of `ralph-orchestrator` and [ADR-0031](../adr/0031-retire-implement-feature-skill.md) for the retirement of the interim `/implement-feature` skill that briefly filled this role. -``` -feature selected → worktree created → issues implemented in topological order → PR opened → issues closed on merge -``` +## What survives across runners -### 1. Feature selection +Regardless of which runner executes a Feature, these conventions hold: -- **Named**: `/implement-feature ` targets `docs/issues//` directly. -- **Auto-select**: `/implement-feature` with no argument scans `docs/issues/` and picks the first Feature (alphabetically by slug) where at least one `NN-*.md` file is `ready-for-agent` and no file is in an unprepped state (`needs-triage`, `needs-info`, `needs-specs`). Partially-completed Features (mix of `resolved` and `ready-for-agent`) are included — the runner resumes from where it stopped. Features where every issue is `resolved`, `closed`, or `rejected` are skipped (nothing left to run). Issues with status `ready-for-human` or `rejected` do not disqualify a feature. -- **Empty queue**: when no qualifying Feature exists, the runner emits `LOOP_COMPLETE` on its own line and exits cleanly. This is the stop signal that `/loop` uses to terminate an overnight run. +- Issues live at `docs/issues//NN-*.md` with the `## What to build` / `## Acceptance criteria` format. +- `## Blocked by` is the canonical execution-order signal ([ADR-0028](../adr/0028-blocked-by-canonical-sequencing.md)). Numeric filename prefixes are a UX convenience, not a contract. +- Each Feature ships as a single PR targeting `develop`. Issues are marked `resolved` on implementation and `closed` after the PR merges. -### 2. Worktree creation +## Related -The runner creates (or reuses) a git worktree and branch: - -- Branch: `feature/afk/` -- Worktree path: `.claude/worktrees/` - -If `.claude/worktrees/` already exists (prior failed run), the runner reuses it — `git worktree add` is skipped and the existing branch retains its committed work. If it does not exist, the runner creates it from `develop`. On success, the worktree is removed after the PR is opened. On failure, it is left in place for inspection. - -### 3. Issue implementation - -Issues are executed via `/tdd` sub-agent invocations in **topological order** derived from `## Blocked by` references (see [Dependency ordering](#dependency-ordering) below). Only `ready-for-agent` issues are executed. `resolved`, `closed`, and `rejected` issues satisfy dependencies but are skipped. `ready-for-human` issues are unsatisfied — if a `ready-for-agent` issue depends on one, the runner halts before executing anything. - -Before each invocation the runner outputs: - -``` -Implementing issue N of M: -``` - -After a successful `/tdd` invocation, the issue file is updated: `Status: ready-for-agent` → `Status: resolved`. - -On failure, a note is appended to the failing issue under `## Comments` (see [Failure behaviour](#failure-behaviour)) and the runner stops. No subsequent issues run. - -### 4. PR and cleanup - -When all issues are resolved, the runner: - -1. Pushes `feature/afk/` to origin. -2. Opens a pull request targeting `develop` via `gh pr create`. The PR title is `feat(): ` and the body references the PRD and lists all resolved issues. -3. Removes the worktree. - -Issues remain at `Status: resolved` until the PR is merged, at which point they are manually marked `closed` (or via a future hook). - -## Context bundle - -Each `/tdd` sub-agent invocation receives a six-part context bundle assembled by the runner: - -| Part | What it contains | Why | -| --------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -| **Issue file** | `## What to build` and `## Acceptance criteria` | Replaces the interactive planning phase in AFK mode | -| **PRD** | `docs/issues//PRD.md` | Carries the "why" and shared vision from the grilling session | -| **Sibling issues** | All other `NN-*.md` files in the feature directory at current state | Shows what is already resolved and what is still pending | -| **Scoped CONTEXT.md** | Plugin or root `CONTEXT.md` (see ADR scope below) | Ensures interface vocabulary and test names match the domain glossary | -| **Scoped ADRs** | All `*.md` files in the scoped ADR directory | Communicates the architectural constraints that bind the implementation | -| **Recent commits** | `git log --oneline -5` | Carries the ideation trail from grilling and PRD work that landed just before the runner | - -### ADR scope - -ADRs are scoped to the domain of the Feature: - -- **Plugin Feature**: the PRD references one or more paths under `apps/claude-code//` → inject `apps/claude-code//CONTEXT.md` and `apps/claude-code//docs/adr/`. Root ADRs are **not** injected. -- **Repo/tooling Feature**: no `apps/claude-code//` references in the PRD → inject root `CONTEXT.md` and root `docs/adr/`. - -## Dependency ordering - -`## Blocked by` is the canonical dependency signal, not numeric filename order. Numeric order is a UX convenience produced by `/to-issues` (it publishes blockers first so numbers usually match), but it is not an execution contract. - -The runner builds a topological execution order from `## Blocked by` references across all `NN-*.md` files before executing anything. - -**Conflict detection**: if an issue A lists issue B in `## Blocked by`, and B has a higher numeric prefix than A, the dependency contradicts the numeric convention. The runner halts before executing any issue and reports: - -``` -Feature Runner error: dependency conflict detected. - Issue NN- is blocked by NN-, but NN- has a higher number than NN-. - This conflicts with the numerical ordering convention. Resolve the ordering manually before re-running. -``` - -`## Blocked by: None`, `## Blocked by: None — can start immediately`, or a missing `## Blocked by` section all mean the issue has no predecessors. - -## Failure behaviour - -When a `/tdd` sub-agent cannot complete an issue: - -1. The issue status is changed to `needs-info`. This prevents the auto-selection path from picking up this Feature on subsequent `/loop` iterations until the developer investigates and restores `ready-for-agent` (or closes/rejects the issue). -2. The runner appends a failure note to the issue file under `## Comments`: - -```markdown -## Comments - -> _This was generated by AI during triage._ - -**Feature Runner failure** — `/tdd` could not complete this issue. Status has been set to `needs-info`. - -The worktree at `.claude/worktrees/` has been left in place for inspection. Once the issue is resolved manually, restore `**Status:** ready-for-agent` and re-run `/implement-feature ` to resume. Alternatively, close or reject the issue if it should not be retried. -``` - -3. The runner stops. No subsequent issues in the Feature are executed. -4. The worktree is left at `.claude/worktrees/` on `feature/afk/` for inspection. - -Re-running `/implement-feature ` after a manual fix resumes from the first `ready-for-agent` issue (already-resolved issues are skipped via the topological filter). - -## Historical cleanup convention - -> **Historical note:** This section describes a one-time cleanup task from the `ralph-orchestrator` retirement (see [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md)). It does not apply to Features created after 2026-05. - -When a spec in `docs/plans/` was marked `done` and a corresponding `docs/issues//` directory exists, those issues were implemented via the retired Spec Runner, not the Feature Runner. They will never be processed by `/implement-feature` and should not remain at `ready-for-agent`. - -**Convention**: manually mark all `NN-*.md` files in `docs/issues//` as `closed` and append a note: - -```markdown -## Comments - -> _This was generated by AI during triage._ - -Marked `closed` — implemented via the Spec Runner (see `docs/plans/.md`, marked `done`). The Feature Runner was not used for this Feature. -``` - -This prevents the auto-selection path from picking up stale Features and keeps the issue tracker accurate. +- [`docs/process/development-workflow.md`](../process/development-workflow.md) — phase-by-phase workflow +- [`docs/process/ai-development.md`](../process/ai-development.md) — deep guide: mental model, context quality, AFK trust chain +- [`docs/agents/issue-tracker.md`](issue-tracker.md) — issue file conventions +- [`docs/agents/triage-labels.md`](triage-labels.md) — 8-state triage vocabulary diff --git a/docs/inbox/README.md b/docs/inbox/README.md deleted file mode 100644 index 8f22680e..00000000 --- a/docs/inbox/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# Inbox - -A low-friction capture zone for raw ideas, bugs, questions, and anything else that pops up mid-conversation and shouldn't be lost. Items here have not yet been grilled, scoped, or assigned a feature slug. - -## How to add an item - -Run `/inbox ` in Claude Code. That's it. - -``` -/inbox pr-review should support GitLab -/inbox unic-confluence image upload support -/inbox investigate windows path issue in auto-format -``` - -A file is created at `docs/inbox/.md`. No follow-up needed. - -## File format - -```markdown ---- -title: pr-review should support GitLab -created: 2026-05-03 ---- - -pr-review should support GitLab -``` - -No `status` field — the location is the status. Every file here is awaiting triage. - -## Graduation - -When you're ready to act on an item: - -1. Open the file and run `/grill-with-docs` or `/grill-me` to refine it -2. Run `/to-prd` to synthesize into a PRD → creates `docs/issues//PRD.md` -3. Manually delete the inbox file (or let the skill handle it) - -Items do **not** move to `docs/issues//` until a scope and slug have been agreed via grilling. - -## Related - -- `docs/agents/issue-tracker.md` — conventions for structured issues post-grilling -- `docs/agents/triage-labels.md` — 8-state vocabulary used in `docs/issues/` (not here) diff --git a/docs/process/ai-development.md b/docs/process/ai-development.md index 7896e401..276e4c3d 100644 --- a/docs/process/ai-development.md +++ b/docs/process/ai-development.md @@ -6,18 +6,17 @@ This guide explains the mental model behind the AI-development workflow, the arc ## 1. The Feature Runner -All AFK execution flows through the Feature Runner. New work enters as Features in the issue tracker (`docs/issues//`). +A **Feature Runner** is the skill that implements a Feature's issues end-to-end in one worktree, branch, and pull request (see root `CONTEXT.md`). New work enters as Features in the issue tracker (`docs/issues//`). | | Feature Runner | | --------------------- | ---------------------------------------------------------- | | **Input** | `docs/issues//NN-*.md` Issue | -| **Invocation** | `/implement-feature` | | **Format** | Descriptive: `## What to build` + `## Acceptance criteria` | -| **Worker** | `/tdd` in non-interactive AFK mode | +| **Worker** | `/tdd` | | **Completion marker** | `Status: resolved` in issue file | -| **Branch** | `feature/afk/` worktree | +| **Branch** | `feature/` (or `feature/afk/` when AFK) | -The Feature Runner is the sole execution path. Infrastructure work (CI, tooling, packages) and product work (plugin features) both enter through the issue tracker — the split is in the issue content, not in which runner handles it. +`unic-dlc-build` (shipped by `unic-archon-dlc`) is the long-term Feature Runner — see [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md) and [ADR-0031](../adr/0031-retire-implement-feature-skill.md). Until it is wired into this repo, the runner is **the developer driving `/tdd` manually**, one issue at a time. Infrastructure work (CI, tooling, packages) and product work (plugin features) both enter through the issue tracker — the split is in the issue content, not in which runner handles it. --- @@ -26,28 +25,28 @@ The Feature Runner is the sole execution path. Infrastructure work (CI, tooling, Every piece of work passes through a pipeline before an agent executes it. Each stage has a human-review checkpoint: ``` -docs/inbox/ ← /inbox: raw capture, no review required +GitHub Issue / /triage ← raw capture, no review required ↓ -/grill-with-docs ← human reviews every branch of the design tree +/grill-with-docs ← human reviews every branch of the design tree ↓ -/to-prd ← human reviews the synthesized PRD +/to-prd ← human reviews the synthesized PRD ↓ -/to-issues ← human reviews the vertical slice breakdown +/to-issues ← human reviews the vertical slice breakdown ↓ -/triage ← human moves issues to ready-for-agent +/triage ← human moves issues to ready-for-agent ↓ -/implement-feature ← agent executes, no human present +/tdd (or unic-dlc-build, when wired up) ← execution ``` -The pipeline is load-bearing. The quality of the autonomous execution at the bottom depends entirely on the quality of the decisions captured at each stage above it. A vague acceptance criterion that slips through triage will produce a vague implementation — and there is no human in the loop to catch it until the PR review. +The pipeline is load-bearing. The quality of the execution at the bottom depends entirely on the quality of the decisions captured at each stage above it. A vague acceptance criterion that slips through triage will produce a vague implementation. Under manual `/tdd` you can still catch it interactively; under AFK execution there is no human in the loop until PR review. --- ## 3. Why context quality determines AFK quality -When `/tdd` runs inside the Feature Runner, it runs non-interactively. In a normal interactive session, `/tdd`'s planning phase asks the user to confirm interface changes and approve which behaviours to test before writing any code. In AFK mode there is no user to ask. +`/tdd` is interactive by default: its planning phase asks the user to confirm interface changes and approve which behaviours to test before writing any code. When `/tdd` is run interactively, that conversation is where most ambiguity is eliminated. -The issue's `## Acceptance criteria` replaces that conversation. The planning phase is not skipped — it was completed during the grilling and issue-writing stages. The Feature Runner simply does not repeat it at runtime. +In AFK mode (the future `unic-dlc-build` path) there is no user to ask. The issue's `## Acceptance criteria` replaces that conversation. The planning phase is not skipped — it must have been completed during the grilling and issue-writing stages. This means there is a direct line between **grilling quality → PRD quality → issue acceptance criteria quality → implementation correctness**. If any link in that chain is weak, the agent produces a _correct-but-wrong_ implementation: code that satisfies the literal issue description but diverges from what you actually intended. @@ -55,32 +54,9 @@ The grilling session (`/grill-with-docs`) is where that chain is forged. It is n --- -## 4. The context bundle +## 4. Writing issues that AFK agents can execute -When the Feature Runner invokes `/tdd` for an issue, it does not pass only the issue file. It assembles a **context bundle** from six sources: - -| Input | Why it matters | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **Issue file** | The `## What to build` and `## Acceptance criteria` — the pre-answered plan | -| **PRD** | The "why" behind the feature; the shared vision from grilling. Without it, the agent reasons from a vertical slice with no broader context | -| **Sibling issue files** | Dependency awareness; "what is already resolved" without the runner summarising | -| **Scoped CONTEXT.md** | Domain glossary — ensures test names and interfaces match the project's vocabulary | -| **Scoped ADRs** | Architectural constraints the implementation must respect | -| **Recent commits (last 5)** | The ideation trail — grilling sessions typically modify CONTEXT.md and ADRs, and those changes land in commits before the runner executes | - -### ADR scoping - -Not all ADRs are relevant to all work. Root `docs/adr/` covers monorepo concerns (versioning, tagging, CI) — those are noise for plugin implementation. Per-plugin `docs/adr/` covers domain-specific decisions that directly constrain what the agent builds. - -The runner infers scope from the PRD: if it references paths under `apps/claude-code//`, inject that plugin's ADRs and CONTEXT.md. If it references paths outside `apps/` (`.claude/`, `docs/`, `packages/`), inject the root ADRs and CONTEXT.md. - -This is why CONTEXT.md and ADRs must be kept current. They are not documentation artifacts — they are runtime inputs to every AFK agent execution. - ---- - -## 5. Writing issues that AFK agents can execute - -An issue's `## Acceptance criteria` is doing two jobs: it is the definition of done for the human reviewer, and it is the planning conversation substitute for the AFK agent. It must be specific enough for both audiences. +An issue's `## Acceptance criteria` is doing two jobs: it is the definition of done for the human reviewer, and it is the planning conversation substitute for any AFK agent. It must be specific enough for both audiences. **Good acceptance criteria** are checkable without ambiguity: @@ -107,37 +83,21 @@ If an issue's acceptance criteria are too vague to verify without judgment, the --- -## 6. Dependency ordering +## 5. Dependency ordering Issues produced by `to-issues` are named with a numeric prefix (`01-`, `02-`, etc.) for human readability. The numbers usually reflect dependency order because `to-issues` publishes blockers first. But **numerical order is not the execution contract**. -The `## Blocked by` field in each issue is the canonical dependency signal. The Feature Runner builds a topological order from `## Blocked by` references before executing anything. If `## Blocked by` and numerical order conflict, the runner halts rather than proceeding silently in the wrong order — because a wrong execution order means downstream issues inherit a broken foundation. +The `## Blocked by` field in each issue is the canonical dependency signal — see [ADR-0028](../adr/0028-blocked-by-canonical-sequencing.md). Any Feature Runner (manual or AFK) must respect `## Blocked by` over filename order. If they conflict, the runner halts rather than proceeding silently in the wrong order — because a wrong execution order means downstream issues inherit a broken foundation. When writing or reviewing issues: always fill in `## Blocked by` accurately. "None — can start immediately" is a valid and important signal. A missing or incorrect `## Blocked by` is more dangerous than a missing acceptance criterion, because the sequencing error compounds silently across every subsequent issue. -The dependency graph also reveals which issues are parallelisable (those with no blockers and no dependents). The Feature Runner serialises all execution by design — parallel issue execution is explicitly out of scope — but understanding which issues are independent helps when manually intervening in a failed run. +The dependency graph also reveals which issues are parallelisable (those with no blockers and no dependents). The current `/tdd`-per-issue flow serialises execution by default; understanding which issues are independent helps when manually intervening in a failed run. --- -## 7. Running overnight +## 6. CONTEXT.md and ADRs as living constraints -The Feature Runner is designed to be composable with `/loop` for unattended overnight execution: - -``` -/loop /implement-feature -``` - -When the queue empties (no qualifying feature exists — see `.claude/skills/implement-feature/SKILL.md` step 0 for the full qualification rule), the runner outputs `LOOP_COMPLETE` and the loop terminates cleanly. - -For overnight runs to succeed, the queue must be in good shape before you start: each target feature must qualify (see SKILL.md step 0) — every issue in `{ready-for-agent, resolved, closed, rejected, ready-for-human}`, no `needs-*` states, no conflicts between `## Blocked by` and numerical order, acceptance criteria specific enough to verify without judgment. A single malformed issue will halt the runner and leave the remainder of the queue unexecuted. - -If a `/tdd` invocation fails mid-feature, the failing issue is flipped to `needs-info` with a failure note appended. The runner stops. Subsequent issues in the same feature do not run — they could inherit a broken foundation. The `needs-info` flip prevents `/loop /implement-feature` from auto-selecting the same feature again until a developer triages the failure. Inspect the failure note, fix the issue or the codebase, set the issue back to `ready-for-agent`, and re-run. (Note: a Ctrl+C interrupt — as opposed to a `/tdd` failure — leaves the issue at `ready-for-agent` so a simple re-run resumes it.) - ---- - -## 8. CONTEXT.md and ADRs as living constraints - -`CONTEXT.md` and `docs/adr/` are not documentation you write once and forget. They are the vocabulary and constraint layer that every agent reads before writing code. Their quality directly affects the quality of every AFK execution. +`CONTEXT.md` and `docs/adr/` are not documentation you write once and forget. They are the vocabulary and constraint layer that every agent reads before writing code. Their quality directly affects the quality of every execution — manual or AFK. **Update CONTEXT.md** when a new domain term is introduced or an existing term is redefined. `/grill-with-docs` does this automatically during a grilling session — terms resolved during grilling are written into CONTEXT.md inline. If a term surfaces outside a grilling session, add it manually. @@ -145,13 +105,18 @@ If a `/tdd` invocation fails mid-feature, the failing issue is flipped to `needs **Never let ADRs drift.** An ADR that no longer reflects the codebase is worse than no ADR — it misdirects the agent. If a decision is superseded, update the original ADR's status to `Superseded by ADR-NNNN` and write the new one. -The commits from your grilling sessions carry this context forward. The Feature Runner injects the last 5 commits into every `/tdd` invocation specifically because grilling sessions modify CONTEXT.md and ADRs — those changes land in commits and the agent needs the ideation trail, not just the final file state. +The commits from your grilling sessions carry this context forward. When `unic-dlc-build` later runs AFK, recent commits are part of the context input precisely because grilling sessions modify CONTEXT.md and ADRs — those changes land in commits and the agent needs the ideation trail, not just the final file state. --- -## 9. Historical: docs/plans/ +## 7. Historical: docs/plans/ and the interim `/implement-feature` skill + +Two earlier execution paths have been retired: + +- **`docs/plans/`** was the intake path for monorepo infrastructure specs (00–17), implemented by `ralph-orchestrator`. All specs are complete and the format is retired as of 2026-05. See [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md). +- **`/implement-feature`** was an interim Claude Code skill that wrapped `/tdd` in a non-interactive sub-agent loop. It was retired in favour of converging on a single Feature Runner (`unic-dlc-build`). See [ADR-0031](../adr/0031-retire-implement-feature-skill.md). [ADRs 0027](../adr/0027-feature-runner-context-bundle.md) and [0029](../adr/0029-feature-runner-afk-invocation.md) describe its internals and are superseded. -`docs/plans/` was the intake path for monorepo infrastructure specs (00–17), implemented by `ralph-orchestrator`. All specs are complete and the format is retired as of 2026-05. If you encounter `docs/issues//` directories whose issues were never closed because they were implemented via a spec, mark them `closed` with a note referencing the spec that covered them. See [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md) for the full retirement decision. +If you encounter `docs/issues//` directories whose issues were never closed because they were implemented via a spec or by the retired skill, mark them `closed` with a note referencing the work that covered them. --- @@ -161,7 +126,6 @@ The commits from your grilling sessions carry this context forward. The Feature - `docs/agents/issue-tracker.md` — issue file conventions - `docs/agents/triage-labels.md` — 8-state triage vocabulary - `docs/adr/0026-tdd-dispatch-by-version-impact.md` — when to use /tdd vs direct implementation (dispatch by version impact) -- `docs/adr/0027-feature-runner-context-bundle.md` — what /tdd receives per invocation - `docs/adr/0028-blocked-by-canonical-sequencing.md` — why ## Blocked by beats filename order -- `docs/adr/0029-feature-runner-afk-invocation.md` — how AFK invocation works - `docs/adr/0030-retire-ralph-adopt-archon-runner.md` — retirement of ralph and docs/plans/ +- `docs/adr/0031-retire-implement-feature-skill.md` — retirement of /implement-feature and /inbox diff --git a/docs/process/development-workflow.md b/docs/process/development-workflow.md index c4e548e7..fd180e92 100644 --- a/docs/process/development-workflow.md +++ b/docs/process/development-workflow.md @@ -1,6 +1,6 @@ # Development Workflow -This repo follows an adapted 8-phase version of Matt Pocock's 7-phase AI development workflow. The phases move from raw idea capture through AFK execution to QA, using the tools already available here. +This repo follows an adapted 8-phase version of Matt Pocock's 7-phase AI development workflow. The phases move from raw idea capture through execution to QA, using the tools already available here. Not every phase is required for every piece of work. A typo fix can go straight to execution. A major feature will touch every phase. @@ -8,15 +8,9 @@ Not every phase is required for every piece of work. A typo fix can go straight ## Phase 1 — Capture the idea -When an idea surfaces mid-conversation or mid-task, capture it without breaking flow: +When an idea surfaces mid-conversation or mid-task, capture it without breaking flow by opening a GitHub Issue directly (or running `/triage` and letting it walk the idea through the state machine). -``` -/inbox -``` - -This drops a file into `docs/inbox/.md`. No follow-up needed. Come back to it during triage. - -If you already have enough context to start grilling immediately, skip the inbox and go straight to Phase 2. +If you already have enough context to start grilling immediately, skip capture and go straight to Phase 2. ## Phase 2 — Grill the idea @@ -30,8 +24,6 @@ Use `/grill-with-docs` when the topic involves domain concepts — it is designe The grilling session walks down every branch of the design tree until the idea is concrete: edge cases surfaced, ambiguities resolved, out-of-scope items named. -**Inbox → grilling transition:** open the inbox file, pass it to `/grill-with-docs` as context, then delete the inbox file once the session completes. - ## Phase 3 — Research (optional) If the work involves an unfamiliar external API, a complex integration, or anything that would require repeated exploration in fresh context windows, cache the findings: @@ -72,24 +64,15 @@ Use the triage labels to track state — see `docs/agents/triage-labels.md` for ## Phase 7 — Execute -### Feature Runner — for `docs/issues/` features +### Manual execution with `/tdd` — current default -Use the Feature Runner when implementing product features tracked as Issues in `docs/issues//`. Once a feature has at least one `ready-for-agent` issue and no unprepped issues (`needs-triage`, `needs-info`, `needs-specs`): +Work through `ready-for-agent` issues one at a time with `/tdd`. For each issue, the `## Acceptance criteria` block stands in for the planning conversation. Mark the issue `resolved` when the implementation lands. Open a PR targeting `develop` once the feature's issues are done. -``` -/implement-feature # target a specific feature -/implement-feature # auto-select next ready feature -``` - -The Feature Runner builds a dependency graph from `## Blocked by` references, invokes `/tdd` non-interactively for each issue in topological order, marks each issue `resolved` on completion, and opens a PR targeting `develop` when all issues are done. - -Compose with `/loop` for overnight queue draining: +Respect the issue ordering signalled by `## Blocked by` (see [ADR-0028](../adr/0028-blocked-by-canonical-sequencing.md)) — a downstream issue inherits a broken foundation if a blocker has not landed. -``` -/loop /implement-feature -``` +### Feature Runner — long-term AFK execution -The runner outputs `LOOP_COMPLETE` when the queue is empty, which terminates the loop cleanly. +The Feature Runner (`unic-dlc-build`, shipped by `unic-archon-dlc`) is the AFK path going forward; see [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md) and [ADR-0031](../adr/0031-retire-implement-feature-skill.md). Until it is wired into this repo, AFK runs are not available — implement manually with `/tdd`. ### Human execution @@ -105,20 +88,19 @@ Human QA often surfaces new issues or improvement ideas — add them back to the ## Quick reference -| Phase | When | Tool | -| -------------------- | ---------------------------------------------- | --------------------------------------------- | -| 1. Capture | Idea surfaces mid-task | `/inbox ` | -| 2. Grill | Before any PRD or spec | `/grill-with-docs` or `/grill-me` | -| 3. Research | Unfamiliar external dependencies | `research.md` (ad hoc) | -| 4. Prototype | Uncertain design or UX | Ad hoc throwaway route | -| 5. PRD | After grilling | `/to-prd` → `docs/issues//PRD.md` | -| 6. Issues | After PRD | `/to-issues` → `docs/issues//-*.md` | -| 7. Execute (Feature) | Issues in `docs/issues/` are `ready-for-agent` | `/implement-feature` (Feature Runner) | -| 8. QA | After execution | QA plan (agent-generated, human-verified) | +| Phase | When | Tool | +| ------------ | ---------------------------------------------- | ----------------------------------------------------------------- | +| 1. Capture | Idea surfaces mid-task | GitHub Issue (or `/triage`) | +| 2. Grill | Before any PRD or spec | `/grill-with-docs` or `/grill-me` | +| 3. Research | Unfamiliar external dependencies | `research.md` (ad hoc) | +| 4. Prototype | Uncertain design or UX | Ad hoc throwaway route | +| 5. PRD | After grilling | `/to-prd` → `docs/issues//PRD.md` | +| 6. Issues | After PRD | `/to-issues` → `docs/issues//-*.md` | +| 7. Execute | Issues in `docs/issues/` are `ready-for-agent` | `/tdd` per issue (Feature Runner via `unic-dlc-build` later) | +| 8. QA | After execution | QA plan (agent-generated, human-verified) | ## Related -- `docs/inbox/README.md` — inbox conventions - `docs/agents/issue-tracker.md` — issue file conventions - `docs/agents/triage-labels.md` — 8-state triage vocabulary - `docs/process/ai-development.md` — deep guide: mental model, context quality, AFK trust chain, key decisions From 618a99b11e6bc5a3a43242d25936e4e8872e6ae7 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 20:56:06 +0200 Subject: [PATCH 2/4] fix: formatting of development workflow table --- docs/process/development-workflow.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/process/development-workflow.md b/docs/process/development-workflow.md index fd180e92..fcd5726b 100644 --- a/docs/process/development-workflow.md +++ b/docs/process/development-workflow.md @@ -88,16 +88,16 @@ Human QA often surfaces new issues or improvement ideas — add them back to the ## Quick reference -| Phase | When | Tool | -| ------------ | ---------------------------------------------- | ----------------------------------------------------------------- | -| 1. Capture | Idea surfaces mid-task | GitHub Issue (or `/triage`) | -| 2. Grill | Before any PRD or spec | `/grill-with-docs` or `/grill-me` | -| 3. Research | Unfamiliar external dependencies | `research.md` (ad hoc) | -| 4. Prototype | Uncertain design or UX | Ad hoc throwaway route | -| 5. PRD | After grilling | `/to-prd` → `docs/issues//PRD.md` | -| 6. Issues | After PRD | `/to-issues` → `docs/issues//-*.md` | -| 7. Execute | Issues in `docs/issues/` are `ready-for-agent` | `/tdd` per issue (Feature Runner via `unic-dlc-build` later) | -| 8. QA | After execution | QA plan (agent-generated, human-verified) | +| Phase | When | Tool | +| ------------ | ---------------------------------------------- | ------------------------------------------------------------ | +| 1. Capture | Idea surfaces mid-task | GitHub Issue (or `/triage`) | +| 2. Grill | Before any PRD or spec | `/grill-with-docs` or `/grill-me` | +| 3. Research | Unfamiliar external dependencies | `research.md` (ad hoc) | +| 4. Prototype | Uncertain design or UX | Ad hoc throwaway route | +| 5. PRD | After grilling | `/to-prd` → `docs/issues//PRD.md` | +| 6. Issues | After PRD | `/to-issues` → `docs/issues//-*.md` | +| 7. Execute | Issues in `docs/issues/` are `ready-for-agent` | `/tdd` per issue (Feature Runner via `unic-dlc-build` later) | +| 8. QA | After execution | QA plan (agent-generated, human-verified) | ## Related From b14835e287d275ffc06a4bc2f5e327b0f6f76701 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 21:08:40 +0200 Subject: [PATCH 3/4] docs: clarify GitHub Issues vs docs/issues// in workflow Phase 1 said capture via GitHub Issue while Phase 5/6 produced docs/issues// artifacts without saying how the two relate. GitHub Issues are the canonical tracker for state and ownership; docs/issues// holds the grilled PRD + ticket files that the Feature Runner consumes. Not every GitHub Issue becomes a Feature directory. Also re-adds docs/inbox/ to the AGENTS.md workspace tree, marked historical, matching how docs/plans/ is listed. Addresses Copilot review on PR #123. Co-Authored-By: Claude Opus 4.7 --- AGENTS.md | 1 + docs/process/ai-development.md | 4 +++- docs/process/development-workflow.md | 2 ++ 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a3f0e63b..60c3a84c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,6 +23,7 @@ packages/ docs/ ├── adr/ # Architectural Decision Records ├── agents/ # Agent skill documentation +├── inbox/ # Retired idea-capture notes (historical) ├── issues/ # Grilled and scoped feature issues ├── plans/ # Retired spec files (historical) ├── process/ # Process and workflow guides diff --git a/docs/process/ai-development.md b/docs/process/ai-development.md index 276e4c3d..87ebecad 100644 --- a/docs/process/ai-development.md +++ b/docs/process/ai-development.md @@ -6,7 +6,9 @@ This guide explains the mental model behind the AI-development workflow, the arc ## 1. The Feature Runner -A **Feature Runner** is the skill that implements a Feature's issues end-to-end in one worktree, branch, and pull request (see root `CONTEXT.md`). New work enters as Features in the issue tracker (`docs/issues//`). +A **Feature Runner** is the skill that implements a Feature's issues end-to-end in one worktree, branch, and pull request (see root `CONTEXT.md`). + +New work enters as a GitHub Issue — the canonical tracker for state and ownership (see [docs/agents/issue-tracker.md](../agents/issue-tracker.md)). Once an idea is grilled into a Feature, `/to-prd` and `/to-issues` materialise a `docs/issues//` directory with the PRD and the numbered ticket files the Feature Runner reads. GitHub Issues remain the source of truth for triage state; `docs/issues//` is the markdown artifact set that captures the grilled scope. Not every GitHub Issue becomes a Feature directory (small fixes never need one). | | Feature Runner | | --------------------- | ---------------------------------------------------------- | diff --git a/docs/process/development-workflow.md b/docs/process/development-workflow.md index fcd5726b..150a2ea1 100644 --- a/docs/process/development-workflow.md +++ b/docs/process/development-workflow.md @@ -10,6 +10,8 @@ Not every phase is required for every piece of work. A typo fix can go straight When an idea surfaces mid-conversation or mid-task, capture it without breaking flow by opening a GitHub Issue directly (or running `/triage` and letting it walk the idea through the state machine). +GitHub Issues are the canonical tracker (see [docs/agents/issue-tracker.md](../agents/issue-tracker.md)) — they hold raw ideas, bug reports, and triage state. Features that get grilled additionally pick up a `docs/issues//` directory in Phase 5, where `/to-prd` and `/to-issues` write the PRD and ticket files the Feature Runner consumes. Not every GitHub Issue grows into a Feature directory — small fixes stay as plain GitHub Issues — and the historical Feature directories under `docs/issues/` predate GitHub being adopted as the primary tracker. + If you already have enough context to start grilling immediately, skip capture and go straight to Phase 2. ## Phase 2 — Grill the idea From 51cec6a6174cdadd8b6f47cd34fc182169f61ebf Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 21:13:59 +0200 Subject: [PATCH 4/4] docs: drop unverified historical claim about docs/issues/ vs GitHub Issues The clause stated that the existing Feature directories under docs/issues/ predate GitHub being adopted as the primary tracker. That ordering isn't documented anywhere, so removing the claim rather than asserting it. Co-Authored-By: Claude Opus 4.7 --- docs/process/development-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/process/development-workflow.md b/docs/process/development-workflow.md index 150a2ea1..fc4282c8 100644 --- a/docs/process/development-workflow.md +++ b/docs/process/development-workflow.md @@ -10,7 +10,7 @@ Not every phase is required for every piece of work. A typo fix can go straight When an idea surfaces mid-conversation or mid-task, capture it without breaking flow by opening a GitHub Issue directly (or running `/triage` and letting it walk the idea through the state machine). -GitHub Issues are the canonical tracker (see [docs/agents/issue-tracker.md](../agents/issue-tracker.md)) — they hold raw ideas, bug reports, and triage state. Features that get grilled additionally pick up a `docs/issues//` directory in Phase 5, where `/to-prd` and `/to-issues` write the PRD and ticket files the Feature Runner consumes. Not every GitHub Issue grows into a Feature directory — small fixes stay as plain GitHub Issues — and the historical Feature directories under `docs/issues/` predate GitHub being adopted as the primary tracker. +GitHub Issues are the canonical tracker (see [docs/agents/issue-tracker.md](../agents/issue-tracker.md)) — they hold raw ideas, bug reports, and triage state. Features that get grilled additionally pick up a `docs/issues//` directory in Phase 5, where `/to-prd` and `/to-issues` write the PRD and ticket files the Feature Runner consumes. Not every GitHub Issue grows into a Feature directory — small fixes stay as plain GitHub Issues. If you already have enough context to start grilling immediately, skip capture and go straight to Phase 2.