Define feature workflow handoffs

This commit is contained in:
Wayner Barrios
2026-07-27 15:04:30 -04:00
parent 9b38cc8a33
commit a3714c09a5
4 changed files with 152 additions and 3 deletions
+25
View File
@@ -17,6 +17,31 @@ These bias toward caution over speed — use judgment on trivial tasks.
- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it.
- **Goal-driven** — turn the task into a concrete success check and iterate until it passes.
## Feature-dev handoff contract
When dispatched by `feature-dev`, follow this contract and choose one approach within the assigned lens.
### Required inputs
- `ASSIGNMENT_ID` and assigned lens
- Approved requirements and exclusions
- Phase 3 decisions
- Exploration synthesis and evidence
- Key files
### Required output
Start with `Status: complete | partial | blocked`, then provide:
- `ASSIGNMENT_ID`
- Scope inspected and scope not inspected
- Assumptions
- Assigned lens
- Requirements-to-components traceability
- Out-of-scope list
- Test plan tied to build steps
- Unresolved blockers
## Core process
### 1. Codebase pattern analysis
+25
View File
@@ -12,6 +12,31 @@ You are an expert code analyst specializing in tracing and understanding feature
Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers.
## Feature-dev handoff contract
When dispatched by `feature-dev`, follow this contract.
### Required inputs
- `ASSIGNMENT_ID` and focus
- Objective
- Requirements and exclusions
- Repository and path scope
- Known context
### Required output
Start with `Status: complete | partial | blocked`, then provide:
- `ASSIGNMENT_ID`
- Scope inspected and scope not inspected
- Focus conclusion
- Entry points and execution flow with `file:line` references
- Dependencies
- Extension points
- Unresolved questions
- 5–10 essential files, or an explanation of why fewer exist
## Analysis approach
### 1. Feature discovery
+48 -3
View File
@@ -25,6 +25,39 @@ These bias toward caution over speed — use judgment on trivial tasks.
- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it.
- **Goal-driven** — turn the task into a concrete success check and iterate until it passes.
## Orchestration contract
Every child assignment must contain exactly this assignment envelope:
```text
ASSIGNMENT_ID:
PHASE:
SPECIALIST:
OBJECTIVE:
SCOPE:
FOCUS:
REQUIREMENTS:
EXCLUSIONS:
PRIOR_INPUTS:
REQUIRED_OUTPUT:
COMPLETION_CRITERIA:
```
Require each child response to start with `Status: complete | partial | blocked`, repeat `ASSIGNMENT_ID`, report covered and uncovered scope, include the phase-specific evidence, and list errors or blockers.
Maintain a coverage ledger containing assignment, focus, status (`pending | valid | blocked | failed | local-fallback`), dispatch count, resume count, retry count, evidence received, uncovered items, and fallback action.
Use this recovery order:
1. Dispatch independent assignments in parallel.
2. If parallel dispatch is unavailable, dispatch only unfinished assignments serially.
3. For a transient timeout, rate-limit, or transport failure, retry it as a fresh task at most once.
4. Validate every response against `REQUIRED_OUTPUT` and `COMPLETION_CRITERIA`.
5. Resume the same child at most once for incomplete or malformed output, naming missing fields.
6. Permission denial does not consume the transient retry.
7. If task dispatch is unavailable or denied, a non-transient failure occurs, or recovery is exhausted, perform the assignment in the parent using the same contract.
8. Preserve valid sibling results, mark fallback usage, and disclose degraded execution in the final summary.
## Phase 1: Discovery
Goal: Understand what needs to be built.
@@ -80,9 +113,21 @@ Goal: Build the feature.
1. Wait for approval.
2. Re-read all relevant files identified earlier.
3. Implement following the chosen architecture.
4. Strictly follow codebase conventions (naming, style, error-handling patterns).
5. Update todos as you progress.
3. Before editing, capture the implementation baseline:
```bash
git rev-parse HEAD
git status --short
git diff
git diff --cached
git ls-files --others --exclude-standard
```
Retain before-content for every dirty or untracked path the implementation may touch.
4. Implement following the chosen architecture.
5. Strictly follow codebase conventions (naming, style, error-handling patterns).
6. After implementation, capture the same inventory and derive an implementation delta containing the baseline commit, pre-existing change ledger, implementation commits, exact changed paths, and staged/unstaged/untracked provenance. If Git is unavailable, use a file-level before/after ledger and label that limitation.
7. Update todos as you progress.
## Phase 6: Quality review
+54
View File
@@ -0,0 +1,54 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { join } from "node:path";
const REPO = process.env.REPO || process.cwd();
const readSkill = (name) => readFileSync(join(REPO, "skills", name, "SKILL.md"), "utf8");
const feature = readSkill("feature-dev");
const explorer = readSkill("code-explorer");
const architect = readSkill("code-architect");
test("feature-dev defines assignments and a coverage ledger", () => {
for (const field of [
"ASSIGNMENT_ID", "PHASE", "SPECIALIST", "OBJECTIVE", "SCOPE",
"FOCUS", "REQUIREMENTS", "EXCLUSIONS", "PRIOR_INPUTS",
"REQUIRED_OUTPUT", "COMPLETION_CRITERIA",
]) assert.ok(feature.includes(field), `missing ${field}`);
assert.match(feature, /coverage ledger/i);
assert.match(feature, /pending.*valid.*blocked.*failed.*local-fallback/is);
});
test("feature-dev bounds recovery and preserves valid sibling results", () => {
assert.match(feature, /resume the same .* at most once/is);
assert.match(feature, /transient .* retry .* at most once/is);
assert.match(feature, /permission denial.*does not consume.*retry/is);
assert.match(feature, /parallel dispatch.*unavailable.*serial/is);
assert.match(feature, /task dispatch.*(unavailable|denied).*parent/is);
assert.match(feature, /preserve.*valid.*sibling/is);
assert.match(feature, /degraded execution/i);
});
test("feature-dev captures the complete before-state before implementation", () => {
for (const command of [
"git rev-parse HEAD", "git status --short", "git diff",
"git diff --cached", "git ls-files --others --exclude-standard",
]) assert.ok(feature.includes(command), command);
assert.ok(
feature.indexOf("git rev-parse HEAD") < feature.indexOf("Implement following the chosen architecture"),
"baseline precedes edits",
);
assert.match(feature, /pre-existing change ledger/i);
assert.match(feature, /implementation delta/i);
});
test("explorer and architect implement the feature-dev handoff", () => {
for (const [name, skill] of [["code-explorer", explorer], ["code-architect", architect]]) {
assert.match(skill, /Feature-dev handoff contract/i, name);
assert.match(skill, /Required inputs/i, name);
assert.match(skill, /Required output/i, name);
assert.match(skill, /Status: complete \| partial \| blocked/i, name);
assert.match(skill, /ASSIGNMENT_ID/i, name);
assert.match(skill, /scope inspected/i, name);
}
});