@engramm/dev-workflow 0.1.6 → 0.1.7

package/README.md

@@ -98,6 +98,8 @@ Violation = immediate pipeline abort.
 | `/vault:bug` | Record a resolved bug |
 | `/vault:adr` | Record an architecture decision |
 | `/vault:debt` | Record tech debt |
+| `/vault:arch` | Architecture analysis: 2-3 options with trade-offs |
+| `/vault:project-review` | Full project audit: 7 perspectives, A-F scoring |
 | `/vault:deps` | Map module dependencies |
 | `/vault:security-scan` | Security audit |
 | `/vault:test-gaps` | Find untested code |

package/dist/lib/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/lib/templates.ts"],"names":[],"mappings":"AA2MA,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACrC,MAAM,CAiBR;AAED,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/lib/templates.ts"],"names":[],"mappings":"AAwNA,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACrC,MAAM,CAiBR;AAED,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC"}

package/dist/lib/templates.js

@@ -184,6 +184,19 @@ Project knowledge is stored in \`.dev-vault/\`:
 4. Review: \`/session:review\`
 5. Handover: \`/session:handover\`
 
+### Vault write rules (ALWAYS ACTIVE)
+
+When the user agrees to a scope change, architecture decision, or deferred work — record IMMEDIATELY:
+
+- **Architecture/scope decision** (user says "yes" to a proposal) → \`vault_record(type: "adr", title, content)\`
+- **Work deferred** (user agrees to postpone something) → \`vault_record(type: "debt", title, content)\`
+- **New gotcha discovered** → append to \`.dev-vault/knowledge.md\` section "Gotchas" (Edit tool, APPEND)
+- **Gameplan changed** (phases reordered, tasks moved) → update \`.dev-vault/gameplan.md\` (Edit tool)
+
+This applies in ALL contexts: during /workflow:dev (including aborted pipelines), free conversation, /vault:arch. Do NOT wait for pipeline completion. Record when user confirms.
+
+Use Edit tool to APPEND to existing vault files. NEVER use Write tool on existing files.
+
 ## Project
 
 <!-- Add project-specific instructions below -->

package/dist/lib/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/lib/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAC/E,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;AAEtD,MAAM,iBAAiB,GAA2B;IAChD,aAAa,EAAE;;;;;;;;;;;;;;;;;CAiBhB;IAEC,mBAAmB,EAAE;;;;;;;;;;;;;;;;;CAiBtB;IAEC,iBAAiB,EAAE;;;;;;;;;;;CAWpB;IAEC,gBAAgB,EAAE;;;;;;;;;;;CAWnB;IAEC,gBAAgB,EAAE;;;;;;;;;;;;;;;;;;;;CAoBnB;IAEC,eAAe,EAAE;;;;;;;;;;;;;;;;;CAiBlB;IAEC,aAAa,EAAE;;;;;;;;;;;;;;CAchB;IAEC,aAAa,EAAE;;;;;;;;;;;;;;CAchB;IAEC,cAAc,EAAE;;;;;;;;;;;;;;;CAejB;IAEC,mBAAmB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCtB;CACA,CAAC;AAEF,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,YAAoC,EAAE;IAEtC,MAAM,IAAI,GAA2B,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,GAAG,SAAS,EAAE,CAAC;IAEzE,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC;IAC/D,IAAI,QAAgB,CAAC;IAErB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7B,QAAQ,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAChD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,uBAAuB,YAAY,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC;IACrB,CAAC;IAED,OAAO,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/lib/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAC/E,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;AAEtD,MAAM,iBAAiB,GAA2B;IAChD,aAAa,EAAE;;;;;;;;;;;;;;;;;CAiBhB;IAEC,mBAAmB,EAAE;;;;;;;;;;;;;;;;;CAiBtB;IAEC,iBAAiB,EAAE;;;;;;;;;;;CAWpB;IAEC,gBAAgB,EAAE;;;;;;;;;;;CAWnB;IAEC,gBAAgB,EAAE;;;;;;;;;;;;;;;;;;;;CAoBnB;IAEC,eAAe,EAAE;;;;;;;;;;;;;;;;;CAiBlB;IAEC,aAAa,EAAE;;;;;;;;;;;;;;CAchB;IAEC,aAAa,EAAE;;;;;;;;;;;;;;CAchB;IAEC,cAAc,EAAE;;;;;;;;;;;;;;;CAejB;IAEC,mBAAmB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDtB;CACA,CAAC;AAEF,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,YAAoC,EAAE;IAEtC,MAAM,IAAI,GAA2B,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,GAAG,SAAS,EAAE,CAAC;IAEzE,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC;IAC/D,IAAI,QAAgB,CAAC;IAErB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7B,QAAQ,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAChD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,uBAAuB,YAAY,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC;IACrB,CAAC;IAED,OAAO,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engramm/dev-workflow",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Development workflow engine with agents and vault for Claude Code",
   "type": "module",
   "bin": {

package/templates/claude/commands/vault/arch.md

@@ -0,0 +1,150 @@
+# /vault:arch — Architecture analysis and decision support
+
+Read-only analysis of an architecture question. Researches codebase and vault, proposes 2-3 solutions with trade-offs, recommends one. Does NOT write code.
+
+## Arguments
+
+`/vault:arch "<question>"` — architecture question or decision to analyze.
+
+Examples:
+- `/vault:arch "как организовать модуль авторизации?"`
+- `/vault:arch "стоит ли разделить этот сервис на два?"`
+- `/vault:arch "выбор между REST и gRPC"`
+- `/vault:arch "как обрабатывать ошибки в pipeline?"`
+
+## Permissions (VIOLATION = ABORT)
+
+- Read files: YES
+- Write/Edit files: FORBIDDEN — analysis only, no code changes
+- Bash: FORBIDDEN
+- Vault writes: FORBIDDEN — user decides whether to create ADR after analysis
+
+## Procedure
+
+### Step 1: Load context
+
+MUST read:
+- `.dev-vault/stack.md` — what technologies are available
+- `.dev-vault/conventions.md` — what patterns are established
+- `.dev-vault/knowledge.md` — existing architecture, gotchas
+- `.dev-vault/gameplan.md` — current phase, priorities
+
+### Step 2: Research codebase
+
+Use Agent (Explore subagent) to:
+1. Find code related to the question (Glob/Grep)
+2. Read relevant files (max 15 files)
+3. Map current architecture around the question area
+4. Identify existing patterns that apply
+5. Check `.dev-vault/architecture/` for related ADR records
+
+### Step 3: Analyze from 3 perspectives
+
+MUST evaluate from ALL 3:
+
+**Maintainability** — how easy to understand, modify, test?
+- Module boundaries clear?
+- Dependencies explicit?
+- Testable in isolation?
+
+**Security** — attack surface, trust boundaries?
+- Where does user input enter?
+- What needs authentication/authorization?
+- Data protection implications?
+
+**Pragmatism** — effort vs value, simplicity, timeline?
+- How much work for each option?
+- Fits current phase from gameplan?
+- Over-engineering risk?
+
+Note conflicts between perspectives explicitly.
+
+### Step 4: Propose solutions
+
+MUST propose **2-3 solutions** (not 1, not 5+). Each MUST include:
+
+1. **Summary** — 1-2 sentences
+2. **How it works** — concrete description with file paths / module names
+3. **Pros** — specific, not generic ("reduces coupling between X and Y")
+4. **Cons** — specific, honest ("adds N files, complexity in Z")
+5. **Fits conventions?** — does it match `.dev-vault/conventions.md`?
+6. **Effort** — small / medium / large
+7. **Risk** — what could go wrong
+
+### Step 5: Recommend
+
+Pick ONE solution. MUST justify with:
+- Why this one over the others
+- Which perspective it optimizes for and why
+- What trade-offs are accepted
+
+## Output format
+
+MUST use this exact format:
+
+```
+══════════════════════════════════
+    ARCH: <question short form>
+══════════════════════════════════
+
+Context:
+  Project: <name> | Branch: <branch> | Phase: <current from gameplan>
+  Related files: <N> analyzed
+  Existing patterns: <relevant conventions/patterns found>
+  Related ADRs: <list or "none">
+
+── Option A: <name> ──
+
+<summary>
+
+How: <concrete description>
+Pros:
+  + <specific pro>
+  + <specific pro>
+Cons:
+  - <specific con>
+  - <specific con>
+Conventions: matches / deviates (<what>)
+Effort: small / medium / large
+Risk: <what could go wrong>
+
+── Option B: <name> ──
+
+<same structure>
+
+── Option C: <name> (if applicable) ──
+
+<same structure>
+
+── Perspective conflicts ──
+
+<if perspectives disagree — describe the conflict and how recommendation resolves it>
+
+── RECOMMENDATION ──
+
+Option <A/B/C>: <name>
+
+Justification:
+  <why this one>
+  <which perspective it optimizes for>
+  <what trade-offs accepted>
+
+Next steps:
+  1. <concrete action>
+  2. <concrete action>
+
+Record this decision? → /vault:adr
+
+══════════════════════════════════
+```
+
+## Rules
+
+- **Read-only** — NEVER modify any file. VIOLATION = ABORT.
+- **MUST propose 2-3 options** — not 1 ("here's what you should do"), not 5+ (analysis paralysis)
+- **Evidence-based** — every claim MUST reference a specific file or vault entry. No "generally speaking".
+- **Concrete** — "move auth logic to src/auth/middleware.ts" not "consider separating concerns"
+- **Stack-aware** — options MUST be feasible with current stack from stack.md
+- **Convention-aware** — flag if option violates conventions.md, justify why it's worth deviating
+- **No code** — describe what to do, not how to implement. Implementation is coder's job.
+- **Offer ADR** — always end with suggestion to record as ADR if decision is significant

package/templates/claude/commands/vault/project-review.md

@@ -0,0 +1,179 @@
+# /vault:project-review — Full project audit
+
+Read-only comprehensive audit of the project. Checks vault, architecture, tests, security, debt, conventions, and production readiness. Does NOT modify any files.
+
+## Permissions
+
+- Read files: YES
+- Write/Edit files: FORBIDDEN
+- Bash: ONLY `npm test`, `npm run build`, `npm run lint` (or stack equivalent) — for checking, not fixing
+
+## Procedure
+
+### Step 1: Load vault context
+
+MUST read ALL vault files:
+- `.dev-vault/stack.md`
+- `.dev-vault/conventions.md`
+- `.dev-vault/knowledge.md`
+- `.dev-vault/gameplan.md`
+- `.dev-vault/phases/` — all phase files (check status: done/pending)
+- `.dev-vault/tasks/` — all tasks (check statuses)
+- `.dev-vault/architecture/` — all ADR records
+- `.dev-vault/bugs/` — all bug records
+- `.dev-vault/debt/` — all debt records
+
+### Step 2: Scan codebase
+
+Use Agent (Explore subagent) to:
+1. Map project structure (top-level dirs, file count per dir)
+2. Read 15-20 representative files (entry points, core modules, tests, configs)
+3. Run `npm test` (or stack equivalent) — record pass/fail count
+4. Run `npm run build` — record success/failure
+5. Search for: TODO, FIXME, HACK, console.log, hardcoded secrets patterns
+
+### Step 3: Analyze from 7 perspectives
+
+MUST evaluate ALL 7 — do not skip any.
+
+**1. Vault completeness**
+- All 4 sections filled (not just frontmatter)?
+- knowledge.md reflects actual architecture (not outdated)?
+- gameplan.md reflects actual progress (phases done match code)?
+- conventions.md matches real code patterns?
+- Unrecorded ADRs, bugs, or debt visible in code?
+
+**2. Architecture**
+- Dependency direction correct? (inner layers don't import outer)
+- Single Responsibility: files/modules do one thing?
+- God objects: any file/class doing too much?
+- Layer separation clean? (no domain logic in controllers, no infra in domain)
+- Circular dependencies?
+
+**3. Test coverage**
+- All public modules have tests?
+- Tests cover: happy path, edge cases, error paths?
+- Test quality: meaningful assertions, not just "doesn't throw"?
+- Test isolation: no shared state?
+- Integration tests exist for critical paths?
+
+**4. Security**
+- OWASP Top 10 patterns in code?
+- Hardcoded secrets, API keys, passwords?
+- Input validation at system boundaries?
+- Auth/AuthZ where needed?
+- Dependencies: known vulnerabilities? (`npm audit` or equivalent)
+
+**5. Tech debt**
+- Recorded debt in `.dev-vault/debt/` — still relevant?
+- Unrecorded debt visible in code? (TODO, FIXME, HACK, workarounds)
+- Files over 300 lines?
+- Functions over 30 lines?
+- Dead code, unused imports?
+
+**6. Production readiness**
+- Error handling: all external calls have error paths + timeouts?
+- Logging: structured logging, no console.log?
+- Config: no hardcoded values that should be env/config?
+- Graceful shutdown?
+- Idempotent operations where needed?
+
+**7. Convention compliance**
+- Code matches `.dev-vault/conventions.md`?
+- Naming consistent? (check 10+ files)
+- File structure matches conventions?
+- Git commit style consistent?
+- Test patterns consistent?
+
+### Step 4: Score and report
+
+## Output format
+
+MUST use this exact format:
+
+```
+══════════════════════════════════
+      PROJECT REVIEW: <name>
+══════════════════════════════════
+
+Branch: <branch>
+Date: <today>
+Files scanned: <N>
+Tests: <N passed> / <N total>
+Build: pass / fail
+
+── SCORES ──
+
+| Perspective          | Score | Issues |
+|---------------------|-------|--------|
+| Vault completeness  | A/B/C/D/F | <N> |
+| Architecture        | A/B/C/D/F | <N> |
+| Test coverage       | A/B/C/D/F | <N> |
+| Security            | A/B/C/D/F | <N> |
+| Tech debt           | A/B/C/D/F | <N> |
+| Production readiness| A/B/C/D/F | <N> |
+| Convention compliance| A/B/C/D/F | <N> |
+
+Overall: <weighted average> / A
+
+── CRITICAL (must fix) ──
+
+- [SEVERITY] [perspective] <file:line> — <issue>
+  Fix: <concrete suggestion>
+
+── HIGH (should fix) ──
+
+- [SEVERITY] [perspective] <file:line> — <issue>
+  Fix: <suggestion>
+
+── MEDIUM (consider) ──
+
+- [perspective] <issue summary>
+
+── VAULT GAPS ──
+
+- <what's missing or outdated in vault>
+
+── TECH DEBT INVENTORY ──
+
+Recorded: <N> items in .dev-vault/debt/
+Unrecorded: <N> items found in code
+- <file:line> — <debt description>
+
+── RECOMMENDATIONS ──
+
+1. <highest priority action>
+2. <second priority>
+3. <third priority>
+
+── GAMEPLAN vs REALITY ──
+
+| Phase | Gameplan status | Actual status | Match |
+|-------|----------------|---------------|-------|
+| Phase 1 | done | <code evidence> | yes/no |
+| Phase 2 | done | <code evidence> | yes/no |
+| ... | ... | ... | ... |
+
+══════════════════════════════════
+```
+
+## Scoring criteria
+
+| Score | Meaning |
+|-------|---------|
+| **A** | Excellent — no issues or only style nits |
+| **B** | Good — minor issues, no blockers |
+| **C** | Acceptable — some issues need attention |
+| **D** | Poor — significant issues, blocks production readiness |
+| **F** | Failing — critical issues, not safe to ship |
+
+## Rules
+
+- **Read-only** — NEVER modify any file. VIOLATION = ABORT.
+- **All 7 perspectives REQUIRED** — do not skip any. Each MUST produce a score.
+- **Evidence-based** — every finding MUST reference a specific file:line. No vague claims.
+- **MUST scan minimum 15 files** — representative sample across all modules
+- **MUST run tests and build** — report actual results, not assumptions
+- **Compare vault with code** — vault says X, code does Y → flag discrepancy
+- **Recorded debt review** — check if existing debt records are still relevant or resolved
+- **No "best-effort"** — if you can't verify something, say "NOT VERIFIED" with reason

package/templates/claude/commands/workflow/dev.md

@@ -58,6 +58,9 @@ Step 7:  Read steps/test.md        → run build + lint + tests
 Step 8:  Read steps/verify.md      → launch Explore agent → COMPLETE / INCOMPLETE
 Step 9:  Read steps/commit.md      → stage + commit (interactive or autonomous)
 Step 9b: Read steps/vault-updates.md → update daily log, task status
+
+ON STOP (pipeline aborted at any step):
+  Read steps/vault-updates.md → record findings, ADR, debt BEFORE stopping
 ```
 
 ### Phase mode

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

@@ -17,6 +17,9 @@ You are a reader agent. Gather context for the task below.
 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
+6. Scan .dev-vault/architecture/ for ADR records related to this task
+7. Scan .dev-vault/bugs/ for known bugs in affected areas
+8. Scan .dev-vault/debt/ for known debt in affected areas
 
 ## Output Format
 CONTEXT:
@@ -26,6 +29,9 @@ Dependencies: [files depending on changes]
 Tests: [existing tests for those files]
 Patterns found: [how similar things are solved]
 Relevant code: [key fragments]
+Related ADRs: [from .dev-vault/architecture/ or "none"]
+Known bugs: [from .dev-vault/bugs/ or "none"]
+Known debt: [from .dev-vault/debt/ or "none"]
 END_CONTEXT
 ```
 

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

@@ -1,8 +1,12 @@
-# Step 9b: Vault updates (after commit)
+# Step 9b: Vault updates (after commit OR pipeline stop)
 
-Orchestrator writes directly to vault after successful commit.
+Orchestrator writes to vault after successful commit AND when pipeline stops/aborts.
 Use **Edit tool** to append — **never overwrite** existing vault files.
 
+**IMPORTANT:** Vault writes MUST happen even if pipeline did not reach COMMIT.
+If pipeline stopped at REVIEW (blocker), TEST (fail), or VERIFY (incomplete) —
+still record findings, decisions, and deferred work before stopping.
+
 ## 1. Daily log
 
 Append to `.dev-vault/daily/<today>.md`: