@engramm/dev-workflow 0.1.0

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

@@ -0,0 +1,36 @@
+# /vault:deps — Map project dependencies
+
+Analyze project dependency graph and record in vault knowledge.
+
+## Procedure
+
+1. Identify dependency sources (`package.json`, `Cargo.toml`, `go.mod`, etc.)
+2. Scan import/use statements across source files (max 20 files)
+3. Build module dependency graph, identify circular dependencies
+4. Find most-imported modules (core modules)
+5. Record in vault via MCP tool `vault_knowledge` section "Architecture"
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+🔗 **Dependency Map — \<projectName\>**
+
+### Core modules
+- **\<module\>** — imported by N files, purpose: \<description\>
+
+### External dependencies
+- **\<library\>** — \<purpose\>, used in \<scope\>
+
+### Module relationships
+- **\<module A\>** → **\<module B\>** — \<relationship\>
+
+### Circular dependencies
+✅ None found / ⚠️ \<list\>
+
+💡 Updated knowledge.md → Architecture
+
+## Rules
+
+- Read-only — never modify source code
+- Focus on architecture-relevant dependencies, not every import

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

@@ -0,0 +1,306 @@
+# /vault:from-spec — Fill vault from project specification
+
+## Output language
+
+All user-facing output (phase headers, tables, questions, summaries) MUST be in Russian (ru-RU).
+Vault file content (stack.md, conventions.md, knowledge.md, gameplan.md) stays in English — it is machine-readable context for agents.
+
+Read SPEC.md (or provided file) and fill all vault sections through phased approval.
+For new projects where only a specification exists and the codebase is empty or minimal.
+
+## Procedure
+
+### Step 1: Find and read spec
+
+1. If argument provided — read that file
+2. Otherwise search: `SPEC.md`, `spec.md`, `docs/SPEC.md`, `.dev-vault/spec.md`
+3. If not found:
+
+> No spec file found. Create SPEC.md in the project root with at least:
+> - Technology stack (languages, frameworks, databases)
+> - Architecture overview
+> - Features / phases
+>
+> Then run `/vault:from-spec` again, or pass a path: `/vault:from-spec docs/my-spec.md`
+
+4. Read the spec file fully
+
+### Step 2: Check vault state
+
+Read all vault files and show current state:
+
+📚 **From spec:** \<filename\> (\<N lines\>)
+
+| Section | Status | Content |
+|---------|--------|---------|
+| stack.md | ✅ / ○ | N technologies / empty |
+| conventions.md | ✅ / ○ | N rules / empty |
+| knowledge.md | ✅ / ○ | N entries / empty |
+| gameplan.md | ✅ / ○ | N phases / empty |
+
+**Plan:** fill \<N\> empty sections from spec. Already filled sections — append only, no overwrite.
+
+**Start?** (yes / edit / skip)
+
+### Step 3: Fill vault (4 phases)
+
+Wait for user confirmation before each phase.
+
+#### Phase 1: stack.md — Technology stack
+
+Extract from spec: languages, frameworks, databases, ORMs, testing tools, infrastructure, dev tools.
+
+If spec is vague (e.g., "modern stack"), propose concrete choices with rationale.
+
+**Version check:** for each library/framework, use context7 MCP (`resolve-library-id` → `query-docs`) to verify the current stable version. Specify exact versions, not ranges. If spec mentions a version — verify it's not outdated.
+
+Show before writing:
+
+📚 **Phase 1/4 — stack.md**
+
+```markdown
+## Languages
+- <language> — <version if mentioned, purpose>
+
+## Frameworks
+- <framework> — <purpose>
+
+## Database
+- <database> — <purpose>
+
+## Testing
+- <tool> — <purpose>
+
+## Infrastructure
+- <tool> — <purpose>
+
+## Dev Tools
+- <tool> — <purpose>
+```
+
+**Only include sections that have content from the spec.**
+
+If stack.md already has content — show diff: what will be added, what already exists.
+
+**Apply?** (yes / edit / skip)
+
+If yes — write to `.dev-vault/stack.md`, preserving existing content.
+
+#### Phase 2: conventions.md — Code conventions
+
+Extract or derive from spec: file structure, naming conventions, code style, patterns, git workflow, testing approach.
+
+If spec does not mention conventions explicitly — derive from the chosen stack:
+- TypeScript project → suggest standard TS conventions
+- Rust project → suggest standard Rust conventions
+- etc.
+
+Reference stack.md from Phase 1 for consistency.
+
+Show before writing:
+
+📚 **Phase 2/4 — conventions.md**
+
+```markdown
+## File Structure
+- <directory> — <purpose>
+
+## Naming
+- Functions: <convention>
+- Types/Classes: <convention>
+- Files: <convention>
+- Database: <convention if applicable>
+
+## Code Style
+- <rule>
+
+## Patterns
+- <pattern>: <where/when>
+
+## Git
+- Branches: <convention>
+- Commits: <convention>
+
+## Testing
+- <approach>
+```
+
+**Apply?** (yes / edit / skip)
+
+#### Phase 3: knowledge.md — Architecture, Data Model, API, Security
+
+This is the most substantial phase. Extract from spec and analyze from multiple perspectives.
+
+**3a: Architecture**
+
+Extract: components, their relationships, data flow, deployment model.
+
+Analyze from 3 perspectives:
+- **Maintainability** — separation of concerns, modularity, testability
+- **Security** — attack surface, trust boundaries, auth/authz model
+- **Pragmatism** — complexity vs value, MVP scope, what to defer
+
+If perspectives conflict — note the conflict and recommend a resolution.
+
+**3b: Data Model (if applicable)**
+
+Extract: entities, relationships, constraints, indexes.
+
+**3c: API (if applicable)**
+
+Extract: endpoints, methods, auth requirements, request/response shapes.
+
+**3d: Security**
+
+Extract: auth mechanism, data protection, input validation, secrets management.
+
+Show before writing:
+
+📚 **Phase 3/4 — knowledge.md**
+
+```markdown
+## Architecture
+- <component> -> <component>: <relationship>
+- Deployment: <model>
+
+## Data Model
+- <entity>: <key fields, relationships>
+
+## API
+- <method> <path> — <purpose> [auth: <type>]
+
+## Security
+- Auth: <mechanism>
+- Data: <protection approach>
+- Validation: <approach>
+
+## Gotchas
+- <non-obvious constraint or decision from spec>
+```
+
+**Only include sections that have content from the spec.**
+
+If knowledge.md already has content — append new sections, do not overwrite existing.
+
+**Apply?** (yes / edit / skip)
+
+#### Phase 4: gameplan.md — Phases and tasks
+
+Break the spec into implementation phases. Each phase should be:
+- Independently deployable (or at least testable)
+- 1-3 days of work
+- Ordered by dependencies (foundation first)
+
+Show before writing:
+
+📚 **Phase 4/4 — gameplan.md**
+
+```markdown
+## Current Phase
+Phase 1: <name>
+
+## Phases
+
+### Phase 1: <name> — <goal>
+- [ ] <task>
+- [ ] <task>
+**Done when:** <completion criteria>
+
+### Phase 2: <name> — <goal>
+- [ ] <task>
+- [ ] <task>
+**Done when:** <completion criteria>
+
+### Phase N: Hardening
+- [ ] Test coverage
+- [ ] Security audit
+- [ ] Performance
+- [ ] Documentation
+**Done when:** <completion criteria>
+
+## Backlog
+- <deferred items from spec>
+```
+
+**Apply?** (yes / edit / skip)
+
+After approval, offer to create tasks and phase files:
+
+> Create tasks from Phase 1? (yes / no)
+
+If yes — create task for each item in Phase 1 via `dev-workflow task create "<title>"`.
+
+> Create executable phase files? (yes / no)
+
+If yes — for each phase in gameplan.md, create `.dev-vault/phases/phase-N-<slug>.md`:
+
+```markdown
+---
+phase: <N>
+name: <phase name>
+status: pending
+depends_on: <N-1 or null>
+---
+
+# Phase N: <name>
+
+## Goal
+<from gameplan "Done when" criteria>
+
+## Tasks
+1. <task from gameplan>
+2. <task from gameplan>
+
+## New files
+- <path> — <purpose>
+
+## Changes to existing files
+- <path> — <what to change>
+
+## Tests
+- <test file> — <what to test>
+```
+
+For each phase file:
+- Derive file/change list from spec requirements for that phase
+- Keep tasks matching gameplan.md exactly
+- "New files" and "Changes" are best-effort estimates from spec context
+
+After creation:
+
+```
+✅ Phase files created:
+  .dev-vault/phases/phase-1-<slug>.md
+  .dev-vault/phases/phase-2-<slug>.md
+  ...
+
+💡 Run: /workflow:dev .dev-vault/phases/phase-1-<slug>.md
+```
+
+### Step 4: Summary
+
+✅ **vault:from-spec complete**
+
+| Phase | Section | Items | Status |
+|-------|---------|-------|--------|
+| 1 | stack.md | +N technologies | ✅ applied / ○ skipped |
+| 2 | conventions.md | +N rules | ✅ applied / ○ skipped |
+| 3 | knowledge.md | +N entries | ✅ applied / ○ skipped |
+| 4 | gameplan.md | +N phases, M tasks | ✅ applied / ○ skipped |
+
+**Next steps:**
+- Review vault: `dev-workflow status`
+- Start Phase 1: `dev-workflow task list` then `dev-workflow task start <id>`
+- Or run full workflow: `dev-workflow run dev "Phase 1 task"`
+
+## 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
+- **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
+- **Multi-perspective on architecture only** — other phases use single-pass analysis
+- **Gameplan phases are coarse** — detailed task breakdown happens in `/task` and `/workflow`

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

@@ -0,0 +1,31 @@
+# /vault:search — Search the vault
+
+Search `.dev-vault/` for relevant information.
+
+## Procedure
+
+1. Take the user's search query
+2. Use MCP tool `vault_search` with the query, or search via Grep
+3. Present results grouped by type
+4. Show 3-5 lines of context around each match
+5. If no results, suggest alternative terms
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+🔍 **Search:** "\<query\>"
+
+### Knowledge
+- **knowledge.md:42** — \<matching line with context\>
+
+### Branches
+- **branches/feature-auth.md:15** — \<matching line\>
+
+### Tasks
+- **tasks/task-001.md:3** — \<matching line\>
+
+### Daily logs
+- **daily/2026-03-30.md:8** — \<matching line\>
+
+**Found N matches across M files.**

package/templates/claude/commands/vault/security-scan.md

@@ -0,0 +1,50 @@
+# /vault:security-scan — Security audit of the codebase
+
+Scan the project for common security issues and record findings in vault.
+
+## Procedure
+
+1. Check for hardcoded secrets:
+   - Search for patterns: `API_KEY`, `SECRET`, `PASSWORD`, `TOKEN`, `PRIVATE_KEY` in source files
+   - Check `.env.example` exists if `.env` is in `.gitignore`
+   - Verify no `.env` files are committed: `git ls-files | grep '\.env'`
+
+2. Check dependency security:
+   - Run `npm audit` or `cargo audit` if available
+   - Check for known vulnerable dependencies
+
+3. Check OWASP Top 10 patterns:
+   - SQL injection: raw queries without parameterization
+   - XSS: unescaped user input in templates
+   - Command injection: `exec()`, `execSync()` with user input
+   - Path traversal: file operations with unsanitized paths
+   - Insecure deserialization: `JSON.parse()` on untrusted input
+
+4. Check configuration:
+   - CORS headers, HTTPS, rate limiting, auth middleware
+
+5. Record findings:
+   - Critical/High → use MCP tool `vault_record` type "bug"
+   - Patterns → use MCP tool `vault_knowledge` section "Security"
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+🔒 **Security Scan — \<projectName\>**
+
+### 🔴 Critical
+- **\<file:line\>** — \<issue description\>
+
+### 🟠 High
+- **\<file:line\>** — \<issue description\>
+
+### 🟡 Medium
+- **\<file:line\>** — \<issue description\>
+
+### ✅ Recommendations
+- \<action item\>
+
+**Scanned N files. Found M issues (C critical, H high, M medium).**
+
+💡 Record high issue? (yes → /vault:bug)

package/templates/claude/commands/vault/test-gaps.md

@@ -0,0 +1,38 @@
+# /vault:test-gaps — Find untested code
+
+Analyze test coverage gaps and record as tech debt.
+
+## Procedure
+
+1. Identify test files (`tests/`, `__tests__/`, `*.test.ts`, `*_test.rs`, `*_test.go`)
+2. Map each test file to the source file it covers
+3. Find source files without tests (exclude types, constants, re-exports)
+4. Analyze test quality for covered files
+5. Run test suite if possible (`npm test` / `cargo test` / `go test ./...`)
+6. Record findings via MCP tools
+
+## Output format
+
+Use this exact format (markdown, not code block):
+
+🧪 **Test Coverage Gaps — \<projectName\>**
+
+### 🔴 Untested
+- **\<file\>** — \<reason it needs tests\>
+
+### 🟡 Under-tested
+- **\<file\>** (N tests) — Missing: \<specific gaps\>
+
+### Quality
+- ✅ \<positive observation\>
+- ⚠️ \<issue\>
+
+**Summary:** N/M source files tested. K need attention.
+
+💡 Record as debt? (yes → /vault:debt for each gap)
+
+## Rules
+
+- Read-only — never create test files (that's the tester agent's job)
+- Focus on significant gaps, not 100% coverage
+- Prioritize: critical paths > error handling > edge cases > utility functions