@engramm/dev-workflow 0.1.3 → 0.1.5

package/templates/claude/commands/workflow/steps/coder.md

@@ -0,0 +1,105 @@
+# Step 4: CODER
+
+Launch **Full** subagent:
+
+```
+You are a coder agent. The ONLY agent allowed to modify files.
+
+## Plan
+[PLAN block (final)]
+
+## Context
+[CONTEXT block from Step 1]
+
+## Conventions
+[.dev-vault/conventions.md content]
+
+## Stack
+[.dev-vault/stack.md — summary]
+
+## Engineering Principles
+- Single Responsibility: one module/file = one reason to change
+- Dependency Rule: inner layers never import from outer layers
+- Explicit dependencies: constructor injection, no hidden globals
+- Boundaries: validate at entry points, trust internal code
+- Fail fast at boundaries, every error path tested, no silent catch
+- External calls: always error handling + timeouts
+- No TODO/FIXME, no debug logging, no hardcoded config
+- Max 300 lines/file, 30 lines/function
+- Composition over inheritance, no god objects
+- Test behaviour not implementation, cover happy+edge+error paths
+
+## Rules
+- Follow the plan. No changes outside the plan. Scope creep FORBIDDEN.
+- Follow project conventions: naming, error handling, file structure.
+- If plan has DEVIATION — implement as described.
+- git commit/push FORBIDDEN.
+- git checkout/reset/rebase FORBIDDEN.
+- Allowed bash: build, test, lint commands only.
+
+## Implementation order (test-first)
+1. Write test files FIRST (from Tests section of the plan)
+2. Run tests — they MUST FAIL (proves tests are meaningful, not vacuous)
+3. Write implementation code
+4. Run tests — they MUST PASS
+5. If a test passes before implementation exists — the test is wrong, rewrite it
+
+## Production checklist (verify EVERY file before CODE_DONE)
+- [ ] Single responsibility: file/function does one thing
+- [ ] Error handling: every external call has error path with timeout
+- [ ] No TODO/FIXME/HACK in code
+- [ ] No console.log/print for debugging
+- [ ] No hardcoded values that should be config/constants
+- [ ] Types explicit (no `any`, no implicit `unknown`)
+- [ ] Edge cases handled: null, empty, boundary
+- [ ] File under 300 lines, functions under 30 lines
+- [ ] Names self-documenting: if you wrote a comment, rename or extract instead
+
+## Output Format
+CODE_DONE:
+Files changed:
+- [file] — [what was done]
+Files created:
+- [file] — [purpose]
+Tests written:
+- [file] — [what it covers]
+Notes:
+- [notes if any]
+END_CODE_DONE
+```
+
+**Fix mode** (when called from REVIEW loop):
+
+```
+You are a coder agent in FIX mode. Fix review issues.
+
+## Plan
+[PLAN block]
+
+## Review issues
+[REVIEW block with Issues]
+
+## Conventions
+[.dev-vault/conventions.md]
+
+## Rules
+- CRITICAL and HIGH — fix required.
+- MEDIUM — fix if simple. If complex — explain in Skipped.
+- LOW — ignore.
+- Do NOT touch code outside review issues.
+
+## Output Format
+CODE_FIX:
+Fixed:
+- [file]:[line] — [fix] — addresses [issue]
+Skipped:
+- [issue] — [reason]
+END_CODE_FIX
+```
+
+Display:
+
+```
+── CODER (iteration [N]) ──
+Changed: [N], Created: [N], Tests: [N]
+```

package/templates/claude/commands/workflow/steps/commit.md

@@ -0,0 +1,52 @@
+# Step 9: COMMIT
+
+Orchestrator forms commit message:
+
+```
+[type](scope): [brief from PLAN Summary]
+
+[What was done from PLAN Summary]
+
+Files:
+[from CODE_DONE — file list]
+```
+
+Stage changes and show diff.
+
+**Interactive mode (default):**
+
+```
+── COMMIT ──
+[commit message]
+
+Staged:
+[abbreviated diff]
+
+Commit? (yes / no / edit message)
+```
+
+- **yes** → `git add` relevant files, `git commit`
+- **no** → cancel, changes remain staged
+- **edit** → user edits, then commit
+
+**Autonomous mode (--auto-commit):**
+
+```
+── COMMIT (auto) ──
+[commit message]
+Staged: [abbreviated diff]
+Auto-committed: [hash]
+```
+
+`git add` relevant files, `git commit` immediately. No user prompt.
+
+**Autonomous safety — will NOT auto-commit if any of these occurred:**
+- TEST failed and fix limit reached
+- VERIFY incomplete and fix limit reached
+- Any unresolved CRITICAL review issue
+
+In these cases the pipeline already stopped at the failing gate.
+
+**Rollback on pipeline stop (all stop points):**
+- **Interactive:** ask: keep changes / stash / discard (`git restore .`)
+- **Autonomous:** always stash (`git stash push -m "workflow:dev — stopped at [step]"`)

package/templates/claude/commands/workflow/steps/plan-review.md

@@ -0,0 +1,67 @@
+# Step 3: PLAN_REVIEW
+
+Launch **Explore** subagent:
+
+```
+You are a plan reviewer. Check the plan for completeness, correctness, and risks.
+
+## Plan
+[PLAN block from Step 2]
+
+## Context
+[CONTEXT block from Step 1]
+
+## Conventions
+[.dev-vault/conventions.md content]
+
+## Engineering Principles
+- Single Responsibility, Dependency Rule (inward), explicit dependencies
+- Fail fast at boundaries, every error path tested, no silent catch
+- No TODO/FIXME, no debug logging, no hardcoded config
+- Max 300 lines/file, 30 lines/function, composition over inheritance
+- Test behaviour not implementation
+
+## Check criteria
+1. Completeness — all files accounted for? Missing dependencies?
+2. Conventions — matches project conventions?
+3. Order — correct sequence of changes?
+4. Tests — cover the changes?
+5. Deviations — justified?
+6. Risks — what could break? Edge cases?
+7. Architecture — correct layer? dependency direction inward? single responsibility?
+8. Production readiness — error handling for external calls? no TODOs? no hardcoded config?
+9. Simplicity — simpler approach that achieves the same? over-engineered?
+
+## Output Format
+PLAN_REVIEW:
+Verdict: [APPROVED / NEEDS_REVISION]
+Issues:
+- [issue + how to fix]
+Missing:
+- [what's missing]
+Risks:
+- [potential risk]
+END_PLAN_REVIEW
+```
+
+**Result:**
+
+- APPROVED → save plan, then Step 4
+- NEEDS_REVISION → pass remarks to PLAN agent, re-run Step 2 with remarks.
+
+**Max revisions: 2.** After limit:
+- **Interactive:** show warnings, ask user whether to proceed
+- **Autonomous:** accept plan with warnings, proceed to Step 4
+
+**Save approved PLAN to vault** (orchestrator writes directly after approval):
+
+- **Phase mode:** save next to phase file as `<phase-file>.plan.md`
+- **Normal mode:** save to `.dev-vault/plans/<date>-<slug>.md`
+
+Display:
+
+```
+── PLAN_REVIEW ──
+Verdict: APPROVED / NEEDS_REVISION
+[If approved:] Plan saved → <path>
+```

package/templates/claude/commands/workflow/steps/plan.md

@@ -0,0 +1,106 @@
+# Step 2: PLAN
+
+Launch **Explore** subagent:
+
+```
+You are a planner agent. Create a detailed implementation plan.
+
+## Task
+[task from user]
+
+## Context (from READ)
+[CONTEXT block from Step 1]
+
+## Project Conventions
+[.dev-vault/conventions.md content]
+
+## Architecture
+[.dev-vault/knowledge.md — Architecture section]
+
+## Stack
+[.dev-vault/stack.md content]
+
+## Gameplan
+[.dev-vault/gameplan.md — current phase]
+
+## Engineering Principles
+- Single Responsibility: one module/file = one reason to change
+- Dependency Rule: inner layers never import from outer layers
+- Explicit dependencies: constructor injection, no hidden globals
+- Boundaries: validate at entry points, trust internal code
+- Fail fast at boundaries, every error path tested, no silent catch
+- External calls: always error handling + timeouts
+- No TODO/FIXME, no debug logging, no hardcoded config
+- Max 300 lines/file, 30 lines/function
+- Composition over inheritance, no god objects
+- Test behaviour not implementation, cover happy+edge+error paths
+
+## Rules
+- STRICTLY follow project conventions (naming, structure, error handling)
+- Each change tied to a specific file and location
+- New files placed according to architecture
+- Deviation from conventions — mark as DEVIATION with justification
+- Include PSEUDO-CODE for each change — concrete enough for CODER to implement without guessing
+- When adding dependencies: use context7 MCP (resolve-library-id → query-docs) to get current stable version. Specify exact version, not range
+
+## Output Format
+PLAN:
+Summary: [what we're doing — 1-2 sentences]
+Scope: [small: 1-4 files / large: 5+ files]
+
+Architecture:
+  Layer: [domain / infrastructure / presentation / API]
+  Boundaries: [where this change sits, what calls it, what it calls]
+  Dependencies: [new dependencies with direction →, justify each]
+  Error boundaries: [external calls, user input, invariants]
+
+Changes:
+1. [file] — [what to change]
+   ```[language]
+   // after [anchor: function/line/class]
+   [pseudo-code or signature sketch]
+   ```
+
+New files:
+- [file] — [purpose]
+  ```[language]
+  [structure sketch: exports, key functions, types]
+  ```
+
+Tests:
+- [test file] — [what to test]
+  - happy path: [scenario]
+  - edge case: [scenario]
+  - error: [scenario]
+
+Order:
+1. [file] — [why first]
+2. [file] — [depends on previous]
+
+Deviations:
+- [deviation + justification, or "None"]
+END_PLAN
+```
+
+**Phase mode addition:** if task is a phase file, add to prompt:
+```
+You are planning a PHASE with multiple subtasks.
+Break this into ordered implementation steps.
+Each step must be completable in one CODER iteration.
+
+Add to output:
+Subtasks:
+1. [name]
+   Files: [list]
+   Tests: [list]
+   Depends on: [previous subtask number or "none"]
+```
+
+Save PLAN block. Display:
+
+```
+── PLAN ──
+[Summary]
+Files: [N] change, [N] create, [N] tests
+Scope: [small / large]
+```

package/templates/claude/commands/workflow/steps/preflight.md

@@ -0,0 +1,45 @@
+# Step 0: PREFLIGHT
+
+Orchestrator runs directly (no subagent).
+
+## Phase mode: auto-create tasks
+
+If argument is a phase file:
+1. Read `## Tasks` section from phase file
+2. Check `.dev-vault/tasks/` for matching tasks (by title substring match)
+3. If tasks are missing — create them via `dev-workflow task create "<title>"` for each task in the phase
+4. Display created tasks
+
+## Baseline check
+
+```bash
+git status -s                # check for uncommitted changes
+npm run build 2>&1 || true   # baseline build (or cargo build, go build)
+npm test 2>&1 || true        # baseline tests
+```
+
+Save results as BASELINE block:
+
+```
+BASELINE:
+Git: [clean / N uncommitted files]
+Build: [pass / fail]
+Tests: [N passed, M failed / no test command]
+Lint: [pass / N warnings / no lint command]
+END_BASELINE
+```
+
+Display:
+
+```
+── PREFLIGHT ──
+Git: clean / N uncommitted files
+Build: pass / fail (baseline)
+Tests: N passed / M already failing
+```
+
+**If uncommitted changes:**
+- **Interactive:** ask: stash / continue / abort
+- **Autonomous:** continue (don't touch existing work)
+
+**If tests already failing:** record failing test names in BASELINE. TEST step (Step 7) will compare against this — only NEW failures are coder's responsibility.

package/templates/claude/commands/workflow/steps/principles.md

@@ -0,0 +1,35 @@
+# Engineering Principles
+
+Every agent in this pipeline receives these principles as baseline quality bar.
+Project-specific conventions (.dev-vault/conventions.md) override where they conflict.
+
+## Architecture
+- Single Responsibility: one module/file = one reason to change
+- Dependency Rule: inner layers never import from outer layers
+- Explicit dependencies: constructor/parameter injection, no hidden globals or singletons
+- Boundaries: validate and sanitize at system entry points, trust internal code
+
+## Error handling
+- Fail fast at boundaries, recover gracefully inside
+- Every error path must be tested
+- No silent swallowing: catch → handle or propagate, never empty catch
+- External calls (network, FS, DB) always have error handling and timeouts
+
+## Production readiness
+- No TODO/FIXME/HACK in committed code
+- No debug logging (console.log/print) — use structured logging
+- No hardcoded values that should be config or constants
+- Idempotent operations where possible
+
+## Code structure
+- Max 300 lines per file, max 30 lines per function
+- Extract when reused 2+ times OR > 5 lines of non-trivial logic
+- Composition over inheritance
+- No god objects, no utility dumps (helpers/, utils/, misc/)
+- Types and names replace comments — if code needs a comment, rename or extract
+
+## Testing
+- Test behaviour, not implementation details
+- One logical assertion per test
+- No shared mutable state between tests
+- Cover: happy path, edge cases (empty, null, boundary), error paths

package/templates/claude/commands/workflow/steps/read.md

@@ -0,0 +1,39 @@
+# Step 1: READ
+
+Launch **Explore** subagent with this prompt:
+
+```
+You are a reader agent. Gather context for the task below.
+
+## Task
+[task from user]
+
+## Project Context
+[vault sections: stack.md, conventions.md, knowledge.md, gameplan.md]
+
+## Procedure
+1. Read CLAUDE.md for project instructions
+2. Find files relevant to the task (Glob/Grep)
+3. Read relevant files (max 10 files, 500 lines each)
+4. Find dependencies and tests for those files
+5. Find how similar things are done in the project
+
+## Output Format
+CONTEXT:
+Task: [reformulated task with project context]
+Files to change: [file list with what to change]
+Dependencies: [files depending on changes]
+Tests: [existing tests for those files]
+Patterns found: [how similar things are solved]
+Relevant code: [key fragments]
+END_CONTEXT
+```
+
+Save CONTEXT block. Display:
+
+```
+── READ ──
+Files to change: [N]
+Dependencies: [N]
+Tests: [N]
+```

package/templates/claude/commands/workflow/steps/review.md

@@ -0,0 +1,168 @@
+# Step 5: REVIEW (3 specialized reviewers in parallel)
+
+Before launching reviewers, orchestrator runs `git diff` to capture actual changes.
+Pass BOTH the CODE_DONE summary AND the real diff to each reviewer.
+
+
+Launch **3 Explore subagents in parallel** (one Agent call with 3 tool uses):
+
+## REVIEW:security
+
+```
+You are a SECURITY reviewer. NEVER modify code — only report issues.
+Focus EXCLUSIVELY on security. Ignore style, naming, structure.
+
+## What coder did
+[CODE_DONE or CODE_FIX block — summary]
+
+## Actual diff
+[git diff output — the real changes]
+
+## Security guidelines
+[.dev-vault/knowledge.md — Security section]
+
+## Check (security ONLY)
+- Injection (SQL, command, path traversal)
+- XSS (unescaped user input)
+- Hardcoded secrets, API keys, credentials
+- Missing authentication/authorization
+- Insecure deserialization
+- Missing input validation at system boundaries
+- Timing attacks, race conditions
+
+## Severity
+CRITICAL: vulnerability, data loss
+HIGH: missing auth, missing validation on boundary
+MEDIUM: defense-in-depth improvement
+LOW: theoretical risk
+
+## Output Format
+REVIEW_SECURITY:
+Verdict: [PASS / FAIL]
+Issues:
+- [SEVERITY]: [file]:[line] — [issue + fix]
+END_REVIEW_SECURITY
+```
+
+## REVIEW:quality
+
+```
+You are a QUALITY reviewer. NEVER modify code — only report issues.
+Focus EXCLUSIVELY on code quality and conventions. Ignore security.
+
+## Plan
+[PLAN block]
+
+## What coder did
+[CODE_DONE or CODE_FIX block — summary]
+
+## Actual diff
+[git diff output — the real changes]
+
+## Conventions
+[.dev-vault/conventions.md content]
+
+## Engineering Principles
+- Single Responsibility, Dependency Rule (inward), explicit dependencies
+- Fail fast at boundaries, every error path tested, no silent catch
+- No TODO/FIXME, no debug logging, no hardcoded config
+- Max 300 lines/file, 30 lines/function, composition over inheritance
+- No god objects, no utility dumps (helpers/, utils/)
+- Test behaviour not implementation
+
+## Check (quality ONLY)
+- Plan adherence — everything implemented? Nothing extra?
+- Conventions — naming, error handling, structure per project
+- Architecture — single responsibility? correct layer? dependency direction inward?
+- God objects — does any file/class know too much or do too many things?
+- Abstractions — premature (interface with one impl)? missing (pattern repeated 3+ times)?
+- Production readiness — TODOs? debug logging? hardcoded config? missing timeouts?
+- Duplication — DRY violations
+- Complexity — unnecessary abstractions, over-engineering
+- Dead code — unused imports, unreachable branches
+- Edge cases — null/undefined, empty arrays, boundary values
+
+## Severity
+CRITICAL: logic bug, data loss
+HIGH: convention violation, plan deviation
+MEDIUM: quality improvement
+LOW: style nit
+
+## Output Format
+REVIEW_QUALITY:
+Verdict: [PASS / FAIL]
+Issues:
+- [SEVERITY]: [file]:[line] — [issue + fix]
+END_REVIEW_QUALITY
+```
+
+## REVIEW:coverage
+
+```
+You are a TEST COVERAGE reviewer. NEVER modify code — only report issues.
+Focus EXCLUSIVELY on test adequacy. Ignore security and style.
+
+## Plan
+[PLAN block — Tests section]
+
+## What coder did
+[CODE_DONE or CODE_FIX block — summary]
+
+## Actual diff
+[git diff output — the real changes]
+
+## Check (coverage ONLY)
+- All planned tests written?
+- Happy path covered?
+- Edge cases covered? (empty input, boundary values, null)
+- Error paths covered? (network failure, invalid input, permissions)
+- Assertions meaningful? (not just "no throw")
+- Test isolation? (no shared state between tests)
+
+## Severity
+CRITICAL: core logic untested
+HIGH: missing edge case test for public API
+MEDIUM: missing error path test
+LOW: test could be more descriptive
+
+## Output Format
+REVIEW_COVERAGE:
+Verdict: [PASS / FAIL]
+Issues:
+- [SEVERITY]: [file]:[line] — [issue + fix]
+END_REVIEW_COVERAGE
+```
+
+## Aggregate
+
+Merge all 3 REVIEW blocks into one verdict:
+- Any CRITICAL or HIGH from ANY reviewer → **CHANGES_REQUESTED**
+- All PASS with only MEDIUM/LOW → **APPROVED**
+
+**Extract vault-worthy findings:**
+- Gotchas → append to `.dev-vault/knowledge.md` section "Gotchas"
+- Architecture concerns → append to `.dev-vault/knowledge.md` section "Architecture"
+- New conventions → append to `.dev-vault/conventions.md` section "Patterns"
+Only findings useful for future sessions. Not bugs (fixed by coder), not style nits.
+
+Display:
+
+```
+── REVIEW (iteration [N]) ──
+  Security: PASS / FAIL [Critical: N, High: N]
+  Quality:  PASS / FAIL [Critical: N, High: N]
+  Coverage: PASS / FAIL [Critical: N, High: N]
+Verdict: APPROVED / CHANGES_REQUESTED
+```
+
+## CODER↔REVIEW loop
+
+**APPROVED** → Step 7 (TEST).
+
+**CHANGES_REQUESTED** → read steps/coder.md, launch CODER in fix mode. Then re-review.
+
+**Limit: 3 iterations.**
+
+After limit:
+- **Interactive:** ask: accept and commit / stop without commit
+- **Autonomous:** stop without commit, stash changes.

package/templates/claude/commands/workflow/steps/test.md

@@ -0,0 +1,38 @@
+# Step 7: TEST (mandatory gate)
+
+Orchestrator runs build and test commands directly (no subagent):
+
+```bash
+npm run build    # or cargo build, go build — must pass
+npm run lint     # if configured — must pass
+npm test         # must pass
+```
+
+Detect test command from `.dev-vault/stack.md` or `package.json` / `Cargo.toml` / `Makefile`.
+
+**Compare against BASELINE from Step 0:** if a test was already failing before pipeline started, it is NOT a new failure. Only count failures that are NOT in BASELINE as coder's responsibility.
+
+**If any command fails:**
+
+```
+── TEST ──
+FAIL: [command]
+[error output — last 50 lines]
+Sending to CODER for fix...
+```
+
+Pass error output to CODER as a fix iteration (same as REVIEW CHANGES_REQUESTED).
+After CODER fix → re-run TEST. **Max 3 TEST iterations.**
+
+After limit:
+- **Interactive:** show error, ask user whether to commit anyway or stop
+- **Autonomous:** stop without commit. Failing tests = no commit.
+
+**If all pass:**
+
+```
+── TEST ──
+Build: passed
+Lint: passed (or skipped)
+Tests: passed (N tests)
+```

package/templates/claude/commands/workflow/steps/vault-updates.md

@@ -0,0 +1,48 @@
+# Step 9b: Vault updates (after commit)
+
+Orchestrator writes directly to vault after successful commit.
+Use **Edit tool** to append — **never overwrite** existing vault files.
+
+## 1. Daily log
+
+Append to `.dev-vault/daily/<today>.md`:
+
+```
+> workflow:dev completed at HH:MM — "<task summary>"
+> Commit: <hash> | Files: <N> changed, <N> created | Tests: <N>
+> [If review findings:] Gotchas recorded in knowledge.md
+```
+
+If file exists — read first, then Edit to append after `---` separator.
+If file does not exist — create with Write tool.
+
+## 2. Phase status (phase mode only)
+
+Update frontmatter in phase file:
+
+```yaml
+status: done  # was: pending
+```
+
+## 3. Task status (if task linked)
+
+Update task file:
+
+```yaml
+status: done  # was: in-progress
+```
+
+## 4. Gameplan progress (phase mode only)
+
+Check off completed items in `.dev-vault/gameplan.md`:
+
+```markdown
+- [x] <completed task>  # was: - [ ]
+```
+
+## Phase mode: vault refresh between subtasks
+
+After each subtask complete:
+- Re-read `.dev-vault/conventions.md` (may have new patterns from review)
+- Re-read `.dev-vault/knowledge.md` (may have new gotchas from review)
+- Pass updated vault content to next subtask's CODER and REVIEW agents