@engramm/dev-workflow 0.1.0

package/templates/claude/agents/researcher.md

@@ -0,0 +1,47 @@
+# Vault Researcher
+
+Read-only agent for gathering project context from the codebase and vault.
+
+## Role
+
+You are a research agent. You ONLY read files, search code, and report findings. You NEVER create or modify files.
+
+## Tools
+
+- Read: YES
+- Glob: YES
+- Grep: YES
+- Bash (read-only: git log, git diff, git status, ls, wc): YES
+- Write: NO
+- Edit: NO
+
+## Procedure
+
+1. Read `.dev-vault/stack.md` and `.dev-vault/conventions.md` for project context
+2. Analyze the task requirements from the user's request
+3. Search the codebase for relevant files using Glob and Grep
+4. Read found files (max 10 files, max 500 lines each)
+5. Check for existing patterns in `.dev-vault/knowledge.md`
+6. Check test files related to the area being investigated
+
+## Output format
+
+```
+CONTEXT:
+Task: <rephrased task>
+Files to change: <list>
+Dependencies: <files that depend on changed files>
+Tests: <existing test files>
+Patterns found: <how similar things are done in the project>
+Relevant code:
+<key snippets with file:line references>
+END_CONTEXT
+```
+
+## Limits
+
+- Max 10 files read
+- Max 500 lines per file
+- No code modifications
+- No file creation
+- Report in under 300 words

package/templates/claude/agents/writer.md

@@ -0,0 +1,29 @@
+# Vault Writer
+
+Agent for creating and updating vault records. Operates exclusively within `.dev-vault/`.
+
+## Role
+
+You create and update knowledge records in the project's `.dev-vault/` directory. You follow Obsidian Markdown conventions.
+
+## Tools
+
+- Read: YES (`.dev-vault/` only)
+- Write: YES (`.dev-vault/` only)
+- Edit: YES (`.dev-vault/` only)
+- Glob: YES
+- Bash (git only): YES
+
+## Rules
+
+1. ONLY write to `.dev-vault/` — never touch project source code
+2. Use Obsidian wikilinks for cross-references: `[[knowledge#Section]]`, `[[branches/feature-x]]`
+3. All files must have YAML frontmatter with `date`, `tags`
+4. Keep entries concise — reference material, not essays
+5. Never include secrets, passwords, API keys, or tokens
+6. Use the templates from `/templates/records/` as starting points
+7. When updating knowledge.md, preserve existing content — append to relevant sections
+
+## When invoked
+
+This agent is called by `/handover`, `/merge`, `/debt`, `/bug`, `/adr` commands to handle the actual file operations.

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

@@ -0,0 +1,41 @@
+# /git:changelog — Generate changelog from git history
+
+Generate a structured changelog from recent commits.
+
+## Procedure
+
+1. Determine range (since last tag, or user-specified)
+2. Collect commits: `git log <range> --oneline --no-merges`
+3. Categorize by prefix: Add/Implement, Update/Refactor, Fix, Remove, Security
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+📋 **Changelog** — \<range description\>
+
+### ✨ Added
+- \<description\> (`\<short hash\>`)
+
+### 🔄 Changed
+- \<description\> (`\<short hash\>`)
+
+### 🐛 Fixed
+- \<description\> (`\<short hash\>`)
+
+### 🗑️ Removed
+- \<description\> (`\<short hash\>`)
+
+### 🔒 Security
+- \<description\> (`\<short hash\>`)
+
+**N commits, M categories.**
+
+💡 Prepend to CHANGELOG.md? (yes / no)
+
+## Rules
+
+- Follow Keep a Changelog format
+- Group related commits
+- Skip merge commits
+- Use present tense

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

@@ -0,0 +1,37 @@
+# /git:merge — Process branch merge
+
+Transfer knowledge from a merged branch into permanent storage.
+
+## Procedure
+
+1. Identify merged branch (from git or user input)
+2. Read `.dev-vault/branches/<branch-slug>.md`
+3. Show what will be transferred:
+
+🔀 **Merge:** \<branch name\>
+
+### Transfer to knowledge.md
+- **Decisions:** \<list from branch context\>
+- **Gotchas:** \<findings discovered\>
+
+### Transfer to gameplan.md
+- **Unfinished:** \<tasks to move to backlog\>
+
+### ❓ Open questions
+- \<flag for user attention\>
+
+**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
+
+✅ **Merged** — branch context archived, knowledge transferred
+
+## Rules
+
+- 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/git/new-branch.md

@@ -0,0 +1,34 @@
+# /git:new-branch — Create branch context
+
+Create a context file for the current git branch in `.dev-vault/branches/`.
+
+## Procedure
+
+1. Run `git branch --show-current`
+2. Determine parent branch
+3. Check for linked tasks via MCP tool `task_list`
+4. Ask user about branch goal if not clear
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+🌿 **New Branch:** \<branch name\>
+
+- **Parent:** \<parent branch\>
+- **Created:** \<today\>
+- **Linked task:** \<task id or none\>
+
+**Goal:** \<what this branch aims to achieve\>
+
+**Save?** (yes / edit goal / skip)
+
+5. If yes → create `.dev-vault/branches/<branch-slug>.md`
+6. Link to gameplan.md phase if applicable
+7. If task exists → suggest `/task start <id>`
+
+✅ **Created** → `.dev-vault/branches/<slug>.md`
+
+## Naming
+
+Branch slug: replace `/` with `-`. Example: `feature/auth-flow` → `feature-auth-flow.md`

package/templates/claude/commands/git/pr-review.md

@@ -0,0 +1,64 @@
+# /git:pr-review — Multi-perspective PR review with vault context
+
+Perform a thorough PR review using project vault knowledge and multiple evaluation perspectives.
+
+## Procedure
+
+1. Get PR diff: `git diff main...HEAD` and `git log main..HEAD --oneline`
+2. Load vault context (conventions, knowledge, stack)
+3. **Evaluate from 5 perspectives:** Security, Quality, Conventions, Completeness, Pragmatism
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+🔍 **PR Review:** \<branch name\>
+
+### Summary
+\<1-2 sentences describing what the PR does\>
+
+**Commits:** N | **Files:** M changed | **Scope:** \<small/medium/large\>
+
+### Convention Compliance
+- ✅ \<passing convention from vault\>
+- ❌ \<violated convention\> — **\<file:line\>**
+
+### ⚠️ Vault Gotchas
+- \<known gotchas from knowledge.md that apply to this PR\>
+
+### Findings by Severity
+
+**🔴 Critical** — \<count or "none"\>
+- **\<file:line\>** — \<issue\> *(perspective: Security/Quality/...)*
+  💡 *Fix:* \<suggestion\>
+
+**🟠 High** — \<count or "none"\>
+- **\<file:line\>** — \<issue\> *(perspective: ...)*
+  💡 *Fix:* \<suggestion\>
+
+**🟡 Medium** — \<count or "none"\>
+- **\<file:line\>** — \<issue\>
+
+**💡 Suggestions**
+- \<improvements\>
+
+### Perspective Verdict
+
+| Perspective | Assessment | Key concern |
+|-------------|-----------|-------------|
+| Security | ✅ / ⚠️ / 🔴 | \<one-line summary\> |
+| Quality | ✅ / ⚠️ / 🔴 | \<summary\> |
+| Conventions | ✅ / ⚠️ / 🔴 | \<summary\> |
+| Completeness | ✅ / ⚠️ / 🔴 | \<summary\> |
+| Pragmatism | ✅ / ⚠️ / 🔴 | \<summary\> |
+
+### ⚠️ Conflicts
+- \<if perspectives disagree: topic, who vs who, resolution\>
+
+### Overall Verdict
+✅ **APPROVE** / ⚠️ **APPROVE with notes** / ❌ **REQUEST_CHANGES**
+
+### 💡 Suggested vault updates
+- \<new gotchas or patterns discovered during review\>
+
+Record findings? → /vault:bug, /vault:adr, /vault:knowledge

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

@@ -0,0 +1,49 @@
+# /session:handover — Save detailed session context
+
+Capture the current session's work into `.dev-vault/` for future sessions.
+
+## Procedure
+
+1. Run `git branch --show-current` and `git diff --stat`
+2. Check workflow status via MCP tool `workflow_status`
+3. Review what was done in this session
+4. Show summary before saving:
+
+📤 **Session Handover — \<date\>**
+
+**Project:** \<name\> | **Branch:** \<branch\>
+
+### ✅ Done
+- \<accomplishment with file/commit reference\>
+
+### 🧠 Key Decisions
+- \<decision with reasoning\>
+
+### ⚠️ Problems & Findings
+- \<gotchas discovered\>
+
+### ❓ Open Questions
+- \<unresolved issues\>
+
+### ➡️ Next Steps
+- \<what to do next session\>
+
+### 🔄 Status
+- **Workflow:** \<state or idle\>
+- **Tasks:** \<linked tasks and status\>
+- **Uncommitted:** \<N files\>
+
+**Save?** (yes / edit / skip)
+
+5. If yes → write to `.dev-vault/daily/<date>.md`
+6. Update branch context and knowledge.md if insights found
+7. Offer to create records: /vault:bug, /vault:adr, /vault:debt
+8. Commit vault changes
+
+✅ **Saved** → `.dev-vault/daily/<date>.md`
+
+## Rules
+
+- Keep entries concise — reference material, not essays
+- Use Obsidian wikilinks for cross-references
+- Never include secrets or tokens

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

@@ -0,0 +1,43 @@
+# /session:resume — Restore session context
+
+Read the project's `.dev-vault/` and load full context for the current session.
+
+## Procedure
+
+1. Run `git branch --show-current`
+2. Read vault files: stack.md, conventions.md, knowledge.md, gameplan.md
+3. Read branch context and 3 most recent daily logs
+4. Check for active tasks and paused workflows
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+📥 **Session Resume — \<projectName\>**
+
+- **Branch:** \<branch\> (\<status\>)
+- **Last session:** \<date\>
+- **Current phase:** \<from gameplan\>
+
+### 🔄 Where we left off
+- \<from branch context or latest daily log\>
+
+### ❓ Open questions
+- \<from branch context\>
+
+### ➡️ Next steps
+- \<from branch context or gameplan\>
+
+### 📋 Active tasks
+- \<task id\> — \<title\> (\<status\>)
+
+### ⏸️ Paused workflow
+- \<workflow name\> — step: \<step\> (run: \<id\>)
+- Resume with: `/workflow resume`
+
+## Special cases
+
+- **Branch main/master** → show gameplan overview and list active branches
+- **New branch without context** → ask user about goal, create branch file
+- **No vault** → suggest `dev-workflow init`
+- **Empty vault files** → suggest `/vault:analyze`

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

@@ -0,0 +1,81 @@
+# /session:review — Multi-perspective code review
+
+Perform a code review of uncommitted changes from multiple perspectives,
+aggregate findings by severity, detect conflicts between perspectives.
+
+## Procedure
+
+1. Run `git diff --stat` to see scope, then `git diff` for details
+2. Load vault context (conventions, stack, knowledge)
+3. **Evaluate from 5 perspectives** (inspired by consensus protocol):
+
+### Perspectives
+
+Each perspective reviews the same diff with different focus:
+
+- **Security** — OWASP Top 10, injection, secrets, path traversal, auth
+- **Quality** — SOLID, DRY, naming, complexity, error handling
+- **Conventions** — project conventions from .dev-vault/conventions.md
+- **Completeness** — edge cases, error paths, missing tests, cleanup
+- **Pragmatism** — effort vs value, over-engineering, simplicity
+
+4. **Aggregate findings** by severity, detect conflicts
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+📝 **Review:** \<branch or description\>
+
+**Scope:** N files changed, M insertions, K deletions
+
+### 🔴 Critical (must fix)
+- **\<file:line\>** — \<issue\> *(perspective: Security/Quality/...)*
+  💡 *Fix:* \<concrete suggestion\>
+
+### 🟠 High (should fix)
+- **\<file:line\>** — \<issue\> *(perspective: ...)*
+  💡 *Fix:* \<suggestion\>
+
+### 🟡 Medium (consider)
+- **\<file:line\>** — \<issue\> *(perspective: ...)*
+
+### 💡 Suggestions
+- \<improvement ideas\>
+
+### ✅ Good
+- \<positive observations from any perspective\>
+
+### ⚠️ Conflicts between perspectives
+
+If perspectives disagree (e.g., Pragmatism says "good enough" but Quality says "refactor"):
+
+- **\<topic\>** — \<perspective A\> vs \<perspective B\>: \<nature of disagreement\>
+  → *Resolution:* \<recommendation or escalate to user\>
+
+### Verdict
+
+| Perspective | Assessment |
+|-------------|-----------|
+| Security | ✅ pass / ⚠️ concerns / 🔴 blocked |
+| Quality | ✅ / ⚠️ / 🔴 |
+| Conventions | ✅ / ⚠️ / 🔴 |
+| Completeness | ✅ / ⚠️ / 🔴 |
+| Pragmatism | ✅ / ⚠️ / 🔴 |
+
+**Overall:** ✅ APPROVE / ⚠️ APPROVE with notes / ❌ REQUEST_CHANGES
+
+**Summary:** N findings (C critical, H high, M medium, S suggestions)
+
+💡 Actions:
+- Bug pattern? → /vault:bug
+- New gotcha? → update knowledge.md
+- Architecture concern? → /vault:adr
+
+## 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

package/templates/claude/commands/task.md

@@ -0,0 +1,52 @@
+# /task — Manage development tasks
+
+Create, track, and manage tasks linked to git branches and workflows.
+
+## Usage
+
+- `/task create "title"` — Create a new task
+- `/task list` — List all tasks
+- `/task start <id>` — Start task (set in-progress)
+- `/task done <id>` — Mark as done
+- `/task show <id>` — Show details
+
+## Output format for /task create
+
+📋 **Task created**
+
+- **ID:** task-001
+- **Title:** \<title\>
+- **Status:** ⚪ pending
+- **Priority:** medium
+
+💡 Start working? `/task start task-001`
+
+## Output format for /task list
+
+📋 **Tasks**
+
+- 🟢 **task-001** — \<title\> (done, high)
+- 🔵 **task-002** — \<title\> (in-progress, medium)
+- ⚪ **task-003** — \<title\> (pending, low)
+- 🔴 **task-004** — \<title\> (blocked, high)
+
+**N tasks** (done: N, in-progress: N, pending: N)
+
+## Output format for /task show
+
+📋 **task-001** — \<title\>
+
+- **Status:** 🟢 done
+- **Priority:** high
+- **Branch:** \<branch or none\>
+- **Workflow:** \<run id or none\>
+- **Created:** \<date\>
+- **Updated:** \<date\>
+
+\<description if any\>
+
+## Task Lifecycle
+
+⚪ pending → 🔵 in-progress → 🟠 review → 🟢 done
+
+↘ 🔴 blocked

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

@@ -0,0 +1,39 @@
+# /vault:adr — Create Architecture Decision Record
+
+Record a significant architectural or design decision in `.dev-vault/architecture/`.
+
+## Procedure
+
+1. Gather from conversation context: Context, Decision, Alternatives, Consequences
+2. Show summary before saving:
+
+📋 **New ADR**
+
+- **Title:** \<decision title\>
+- **Date:** \<today\>
+- **Status:** accepted
+
+**Context:** \<why needed\>
+
+**Decision:** \<what was decided\>
+
+**Alternatives considered:**
+- **\<option A\>** — \<pros/cons\>
+- **\<option B\>** — \<pros/cons\>
+
+**Consequences:** \<trade-offs\>
+
+**Save?** (yes / edit / skip)
+
+3. If yes → use MCP tool `vault_record` type "adr" or create file directly
+4. Confirm:
+
+✅ **Saved** → `.dev-vault/architecture/<date>-<slug>.md`
+
+💡 Updated knowledge.md if decision impacts patterns
+
+## When to use
+
+- Choosing between frameworks, libraries, or approaches
+- Defining data models or API contracts
+- Changing project structure or conventions

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

@@ -0,0 +1,110 @@
+# /vault:analyze — Deep project analysis with phased planning
+
+Analyze the codebase and fill all vault sections with discovered information.
+Uses phased approach with gate criteria before each write.
+
+## Step 1: Check existing vault state
+
+Read all vault files and show current state:
+
+🔍 **Analyzing \<projectName\>...**
+
+**Step 1/4 — Vault state**
+
+| Section | Status | Content |
+|---------|--------|---------|
+| stack.md | ✅ / ○ | N items / empty |
+| conventions.md | ✅ / ○ | N rules / empty |
+| knowledge.md | ✅ / ○ | N entries / empty |
+| gameplan.md | ✅ / ○ | N phases / empty |
+
+Read: `.dev-vault/stack.md`, `.dev-vault/conventions.md`, `.dev-vault/knowledge.md`, `.dev-vault/gameplan.md`
+
+## Step 2: Scan project structure
+
+1. Run `find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/target/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/.dev-vault/*' | head -100`
+2. Identify project layout
+
+📁 **Project:** \<layout type\> — N source files across M directories
+
+## Step 3: Analyze code
+
+**IMPORTANT:** Use a single Agent (subagent_type: Explore) to read all files at once.
+Do NOT read files one by one — this creates too many tool calls in the UI.
+
+Pick 5-10 diverse files: entry points, core modules, tests, configs.
+
+Extract: File Structure, Naming, Code Style, Patterns, Testing conventions.
+
+## Step 4: Phased plan with gate criteria
+
+📋 **Analysis plan:**
+
+### Phase 1: Conventions (gate: user approval)
+- → **conventions.md** — add File Structure (N), Naming (N), Code Style (N)
+- Gate: show items, user confirms
+
+### Phase 2: Knowledge (gate: phase 1 complete)
+- → **knowledge.md** — add Architecture (N), Gotchas (N)
+- Gate: show items, user confirms
+
+### Phase 3: Verification (gate: phase 2 complete)
+- Verify no contradictions between conventions and knowledge
+- Verify references point to real files
+
+**Skip:**
+- ✅ **stack.md** — already filled (verify only)
+- ○ **gameplan.md** — requires human input
+
+**Start Phase 1?** (yes / preview all / skip)
+
+**Wait for user confirmation before each phase.**
+
+## Step 5: Execute phases
+
+For each phase:
+1. Show exactly what will be written
+2. Wait for approval
+3. Write to vault via MCP tools or direct edit
+4. Confirm what was written
+5. Proceed to next phase
+
+**Preserve existing content** — only append new information.
+
+### conventions.md sections:
+- `## File Structure`: `- <directory> — <purpose>`
+- `## Naming`: `- Functions: <convention>`, `- Types: <convention>`, `- Files: <convention>`
+- `## Code Style`: `- Error handling: <pattern>`, `- Logging: <library>`
+- `## Patterns`: `- <pattern>: <where used>`
+
+### knowledge.md sections:
+- `## Architecture`: `- <component> → <component>: <relationship>`
+- `## Gotchas`: `- <gotcha from code or README>`
+
+## Step 6: Summary
+
+✅ **Analyze complete**
+
+| Phase | Section | Items added | Status |
+|-------|---------|-------------|--------|
+| 1 | conventions.md | +N | ✅ |
+| 2 | knowledge.md | +N | ✅ |
+| 3 | verification | N checks | ✅ / ⚠️ |
+
+**Key findings:**
+- \<most important discovery\>
+- \<second finding\>
+- \<third finding\>
+
+💡 **Next:** fill gameplan.md manually, then /session:review
+
+## 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"
+- **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

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

@@ -0,0 +1,31 @@
+# /vault:bug — Record a resolved bug
+
+Create a bug log in `.dev-vault/bugs/` for non-trivial bugs that were solved.
+
+## Procedure
+
+1. Gather: Symptoms, Root cause, Fix, Prevention, Severity
+2. Show summary before saving:
+
+🐛 **Bug Record**
+
+- **Severity:** 🔴 critical / 🟠 high / 🟡 medium / 🟢 low
+- **Title:** \<brief description\>
+
+**Symptoms:** \<how it showed up\>
+**Root cause:** \<why it happened\>
+**Fix:** \<what was done — reference files/commits\>
+**Prevention:** \<how to avoid in future\>
+
+**Save?** (yes / edit / skip)
+
+3. If yes → use MCP tool `vault_record` type "bug"
+4. Confirm:
+
+✅ **Saved** → `.dev-vault/bugs/<date>-<slug>.md`
+
+💡 Updated knowledge.md → Gotchas (if pattern revealed)
+
+## When to use
+
+Only for non-trivial bugs worth remembering. Simple typos don't need a record.

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

@@ -0,0 +1,28 @@
+# /vault:debt — Record tech debt
+
+Create a tech debt record in `.dev-vault/debt/`.
+
+## Procedure
+
+1. Gather: What, Why deferred, Priority, Effort, Risk
+2. Show summary before saving:
+
+📝 **Tech Debt**
+
+- **Priority:** 🔴 high / 🟡 medium / 🟢 low
+- **Effort:** small / medium / large
+- **Title:** \<title\>
+
+**Problem:** \<what's wrong\>
+**Why deferred:** \<context\>
+**Proposal:** \<how to fix\>
+**Risk if ignored:** \<consequences\>
+
+**Save?** (yes / edit / skip)
+
+3. If yes → use MCP tool `vault_record` type "debt"
+4. Confirm:
+
+✅ **Saved** → `.dev-vault/debt/<date>-<slug>.md`
+
+💡 Added to gameplan.md backlog. Consider: `/task create "<title>"`