@engramm/dev-workflow 0.1.4 → 0.1.6

package/templates/agents/reader.md

@@ -15,6 +15,13 @@ You are a reader agent for {{projectName}}.
 Gather and summarize project context. You read code, documentation,
 and vault data to build a complete picture of the current state.
 
+## Permissions (VIOLATION = ABORT)
+
+- Read files: YES
+- Write/Edit files: FORBIDDEN
+- Bash commands: FORBIDDEN
+- Max files: 10, max 500 lines each
+
 ## Project Context
 
 ### Stack

package/templates/agents/reviewer.md

@@ -13,7 +13,14 @@ You are a reviewer agent for {{projectName}}.
 ## Your Role
 
 Review code changes for quality, security, and convention compliance.
-You do NOT modify any files. Your output is a review report.
+Your output is a review report. You NEVER fix code — only report issues.
+
+## Permissions (VIOLATION = ABORT)
+
+- Read files: YES
+- Write/Edit files: FORBIDDEN — you MUST NOT modify, create, or delete any file
+- Bash commands: FORBIDDEN
+- If you see a problem: describe it and suggest a fix. Do NOT apply the fix.
 
 ## Project Context
 

package/templates/agents/tester.md

@@ -12,8 +12,14 @@ You are a tester agent for {{projectName}}.
 
 ## Your Role
 
-Write tests and verify they pass. You may read any file
-but only create or modify files in tests/.
+Write tests and verify they pass.
+
+## Permissions (VIOLATION = ABORT)
+
+- Read files: YES (any file)
+- Write/Edit: ONLY files in tests/ — FORBIDDEN outside tests/
+- Bash: ONLY test commands (npm test, cargo test, pytest) — no other bash
+- You MUST NOT modify source code. Only tests.
 
 ## Project Context
 

package/templates/claude/commands/git/merge.md

@@ -23,15 +23,17 @@ Transfer knowledge from a merged branch into permanent storage.
 **Proceed?** (yes / skip)
 
 4. If yes:
-   - Append decisions/gotchas to knowledge.md
-   - Move unfinished to gameplan.md backlog
-   - Set branch status: `merged`, add `merged: <today>`
-   - Update gameplan.md: mark completed tasks
+   - APPEND decisions/gotchas to knowledge.md (read first, Edit tool to append to section)
+   - APPEND unfinished to gameplan.md backlog (read first, Edit tool to append)
+   - Edit branch file: set `status: merged`, add `merged: <today>` (Edit tool, not Write)
+   - Edit gameplan.md: mark completed tasks with `[x]` (Edit tool)
 
 ✅ **Merged** — branch context archived, knowledge transferred
 
 ## Rules
 
+- **APPEND ONLY** — never overwrite existing vault files. Read first, then append with Edit tool.
+- Use Edit tool for all vault modifications, not Write tool (Write overwrites the entire file)
 - Never delete branch file — keep as historical record
 - Transfer only lasting knowledge, not session-specific details
 - If abandoned: set `status: abandoned` with reason

package/templates/claude/commands/session/handover.md

@@ -35,8 +35,13 @@ Capture the current session's work into `.dev-vault/` for future sessions.
 
 **Save?** (yes / edit / skip)
 
-5. If yes → write to `.dev-vault/daily/<date>.md`
+5. If yes → APPEND to `.dev-vault/daily/<date>.md`
+   - If file exists: read it first, then use Edit tool to append at the end (after `---` separator)
+   - If file does not exist: create with Write tool
+   - NEVER overwrite existing daily log content
 6. Update branch context and knowledge.md if insights found
+   - knowledge.md: use Edit tool to append to specific section, preserve existing
+   - branch context: use Edit tool to update status field only
 7. Offer to create records: /vault:bug, /vault:adr, /vault:debt
 8. Commit vault changes
 
@@ -44,6 +49,9 @@ Capture the current session's work into `.dev-vault/` for future sessions.
 
 ## Rules
 
-- Keep entries concise — reference material, not essays
-- Use Obsidian wikilinks for cross-references
-- Never include secrets or tokens
+- **APPEND ONLY** — NEVER overwrite existing vault files. Read first, then Edit to append.
+- **Edit tool ONLY** — NEVER use Write tool on existing files (it overwrites entirely)
+- **Max 3 sentences per section** — reference material, not essays
+- **MUST include** file paths or commit hashes in "Done" section — no vague descriptions
+- **MUST create** vault records (/vault:bug, /vault:adr, /vault:debt) if findings qualify — not "offer", DO IT
+- NEVER include secrets or tokens

package/templates/claude/commands/session/resume.md

@@ -41,3 +41,11 @@ Use this exact format (markdown, not code block):
 - **New branch without context** → ask user about goal, create branch file
 - **No vault** → suggest `dev-workflow init`
 - **Empty vault files** → suggest `/vault:analyze`
+
+## Rules
+
+- **MUST read ALL 4 vault files** (stack, conventions, knowledge, gameplan) — do not skip any
+- **MUST check** for active tasks and paused workflows — not optional
+- **MUST display** branch context if not on main — not optional
+- **Resume complete when:** all vault sections shown + branch context + tasks + workflow status
+- Read-only — NEVER modify vault files during resume

package/templates/claude/commands/session/review.md

@@ -74,8 +74,10 @@ If perspectives disagree (e.g., Pragmatism says "good enough" but Quality says "
 
 ## Rules
 
-- Read-only — never modify project code
-- Reference specific files and line numbers
-- Each finding tagged with source perspective
-- Conflicts: if Security blocks but Pragmatism approves → Security wins
-- Critical from ANY perspective → overall REQUEST_CHANGES
+- **Read-only** — NEVER modify project code. VIOLATION = ABORT.
+- **All 5 perspectives REQUIRED** — do not skip any. Each MUST produce a verdict.
+- **Reference specific files and line numbers** — no vague "there might be issues"
+- **Each finding MUST be tagged** with source perspective (Security/Quality/Conventions/Completeness/Pragmatism)
+- **Conflict resolution:** Security > Correctness > Conventions > Pragmatism. Higher priority wins.
+- **Critical from ANY perspective** → overall REQUEST_CHANGES
+- **APPEND ONLY** for vault updates — use Edit tool, NEVER Write tool on existing files

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

@@ -65,11 +65,11 @@ Extract: File Structure, Naming, Code Style, Patterns, Testing conventions.
 For each phase:
 1. Show exactly what will be written
 2. Wait for approval
-3. Write to vault via MCP tools or direct edit
+3. Write to vault: read file first, then use Edit tool to APPEND (never Write tool which overwrites)
 4. Confirm what was written
 5. Proceed to next phase
 
-**Preserve existing content** — only append new information.
+**APPEND ONLY** — read existing content first, then append. Never use Write tool on existing vault files.
 
 ### conventions.md sections:
 - `## File Structure`: `- <directory> — <purpose>`
@@ -100,11 +100,12 @@ For each phase:
 
 ## Rules
 
-- **Gate criteria:** each phase requires explicit user approval
-- **Preserve existing content** — never overwrite, only append
-- **Be specific** — "functions use snake_case" not "standard naming"
-- **Reference files** — "error handling in cli/src/main.rs uses anyhow"
+- **Gate criteria:** each phase REQUIRES explicit user approval. Do NOT skip.
+- **APPEND ONLY** — use Edit tool. NEVER use Write tool on existing vault files.
+- **Be specific** — "functions use snake_case" not "standard naming". Vague = rewrite.
+- **Reference files** — MUST include file path: "error handling in cli/src/main.rs uses anyhow"
 - **Skip gameplan.md** — roadmap is human-authored
 - **Don't add utility crates/packages to stack.md** — only frameworks, ORMs, test runners
-- Read max 15 files
-- Never include secrets or credentials
+- **MUST read minimum 10 files, maximum 15** — not fewer, not "a few"
+- **Verification:** after each phase, verify no contradictions with existing vault content
+- NEVER include secrets or credentials

package/templates/claude/commands/vault/from-spec.md

@@ -300,12 +300,15 @@ After creation:
 
 ## Rules
 
-- **Gate criteria:** each phase requires explicit user approval before writing
-- **Preserve existing content** — never overwrite filled sections, only append
-- **Be specific** — "TypeScript 5.x with strict mode" not "typed language"
-- **Derive when implicit** — if spec says "REST API" but not "Express", propose based on stack
+- **Gate criteria:** each phase REQUIRES explicit user approval before writing. Do NOT skip approval.
+- **APPEND ONLY** — use Edit tool to append. NEVER use Write tool on existing vault files.
+- **Be specific** — "TypeScript 5.x with strict mode" not "typed language". Vague = rewrite.
+- **Verify versions** — MUST use context7 MCP for library versions. No guessing from training data.
+- **Derive when implicit** — if spec says "REST API" but not "Express", MUST research and propose with rationale
 - **Skip empty phases** — if spec has no data model, skip 3b entirely
-- **No secrets** — never include API keys, passwords, or credentials
-- **Reference spec** — cite which part of the spec each item comes from
+- **No secrets** — NEVER include API keys, passwords, or credentials
+- **Reference spec** — MUST cite which part of the spec each item comes from
+- **No "best-effort"** — every item MUST be verified against spec or codebase
 - **Multi-perspective on architecture only** — other phases use single-pass analysis
 - **Gameplan phases are coarse** — detailed task breakdown happens in `/task` and `/workflow`
+- **Gameplan phases are coarse** — detailed task breakdown happens in `/task` and `/workflow`