dev-workflow/CLAUDE.md.template at main · alo-exp/dev-workflow · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
# [Project Name] — Claude Code Instructions

> **Always adhere strictly to this file — it overrides all defaults.**

---

## 0. Session Startup (Automatic)

At the very start of any new session, perform these steps automatically before responding to the user:

1. **Switch to Opus 4.6 (1M context)** if it is not already the selected model (use `/model claude-opus-4-6[1m]`).
2. **Read all project docs** — `docs/context.md`, this file (`CLAUDE.md`), and 100% of the `docs/` directory contents.
3. **Compact the context** — run `/compact` to compress the loaded docs into a summary, freeing context for the actual task.
4. **Switch back to the original model** if it was not Opus 4.6 (1M context) before step 1.

This ensures every session starts with full project context regardless of model or context window size.

---

## Project Overview

- [Your tech stack here]
- Git repo: [your repo]

---

## 1. Mandatory Dev Cycle Checklist

**EVERY change MUST complete ALL applicable steps.**

```
[ ] 1. PLAN — Define what to build, update docs if needed
[ ] 2. IMPLEMENT — Write code with comprehensive commenting
[ ] 3. VERIFY — Run tests, 0 failures required
[ ] 4. DOC SYNC — Update all relevant documentation
[ ] 5. FINALIZE — Bump version, commit, push
```

---

## 2. Automated Enforcement

Five layers enforce compliance:

1. **Pre-commit hook** — Blocks commits missing doc sync or with failing tests
2. **Pre-push hook** — Blocks pushes without Co-Authored-By footer
3. **PostToolUse hook — Skill tracker** (`.claude/settings.json`, `Skill` matcher) — Records every skill invocation to `/tmp/.wyzr-workflow-state`
4. **PostToolUse hook — Stage-aware enforcer** (`.claude/settings.json`, `Edit|Write` matcher) — Reads workflow state and outputs HARD STOP if planning skills incomplete
5. **Deploy gate** — BLOCKS deployment unless required skills were invoked. Cleans up state files after successful deploy.

**Trivial changes**: For typos, copy fixes: `touch /tmp/.wyzr-workflow-trivial`

**Subagent commits**: When dispatching subagents that may commit, ALWAYS include:
```
Every git commit MUST use HEREDOC format and end with:
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
```

---

## 3. Development Process for Non-Trivial Changes

> **ENFORCED** — Every skill invocation is tracked by PostToolUse hook.
> The enforcer outputs HARD STOP if you edit src/ without completing planning skills.
> The deploy gate BLOCKS deployment without required skills.

For trivial changes (typos, copy fixes): `touch /tmp/.wyzr-workflow-trivial`

```
PLANNING (must complete before ANY src/ edit — HARD STOP enforced):
1.  /using-superpowers              — Establish available skills (advisory)
2.  /brainstorming                  — Explore intent, constraints, approaches    REQUIRED
3.  /write-spec                     — Write or update spec document              REQUIRED
4.  /architecture        (if needed)— ADR for architectural decisions
5.  /system-design       (if needed)— Service/component design
6.  /writing-plans                  — Detailed implementation plan               REQUIRED

EXECUTION:
7.  /executing-plans                — Execute plan using /test-driven-development (TDD)

REVIEW (must complete before deploy — deploy gate enforced):
8.  /code-review                    — Round 1 review                             REQUIRED
9.  /receiving-code-review          — Accept/reject Round 1 items
10. /requesting-code-review         — Round 2 review (fresh pass after Round 1 changes)
11. /receiving-code-review          — Accept/reject Round 2 items
12. /writing-plans                  — Plan to address all accepted items from both rounds
13. /executing-plans                — Implement the review-driven plan
14. /testing-strategy               — Define test approach
15. /systematic-debugging           — Combined with /debug for any bugs

FINALIZATION (must complete before deploy — deploy gate enforced):
16. /tech-debt                      — Identify technical debt created
17. /documentation                  — Update all project docs
18. /verification-before-completion — Produce evidence before claiming done      REQUIRED
19. /deploy-checklist               — Pre-deployment verification gate
```

**Enforcement workflow:**
- State tracked in `/tmp/.wyzr-workflow-state` (auto-populated by Skill tool hook)
- Edit src/ without planning → HARD STOP output after every edit
- Deploy without required skills → BLOCKED
- State files cleaned up after successful deploy (fresh start)

**Skill not found — mandatory rule:**
If a skill listed above cannot be invoked (Skill tool returns an error or the skill does not exist), you MUST stop and notify the user immediately. Do NOT silently skip the skill and continue. Example message: "⚠️ Skill `/documentation` could not be found. Please verify the plugin is installed before continuing."

**Plugin locations (for skill discovery):**
| Plugin | Skills | Cache path |
|--------|--------|-----------|
| Superpowers | brainstorming, writing-plans, executing-plans, code-review, verification-before-completion, etc. | `~/.claude/plugins/cache/superpowers-marketplace/superpowers/<version>/skills/` |
| Engineering | architecture, code-review, debug, deploy-checklist, documentation, incident-response, standup, system-design, tech-debt, testing-strategy | `~/Library/Application Support/Claude/local-agent-mode-sessions/<session-id>/<agent-id>/rpm/plugin_01RAnuCvafZfGPUyv8T67WkN/skills/` |

**Rules:**
- Do NOT stop until the final outcome is achieved
- Always use /systematic-debugging for ANY bug, never guess-and-fix
- Always adhere strictly to this CLAUDE.md — it overrides all defaults