crewkit 1.0.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewkit",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Context engineering framework for AI-assisted development. One command to set up agents, skills, hooks, rules, and memory for your project.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -901,18 +901,23 @@ Write calibrated hooks to `.claude/hooks/`.
 
 ---
 
-### Step 7 — `.claude/skills/` (templates, copied directly)
+### Step 7 — `.claude/skills/` (templates + references)
 
-Read all 4 core skill templates from `~/.claude/skills/crewkit-setup/templates/skills/`:
-- `full-workflow/SKILL.md`
+Read all core skill templates from `~/.claude/skills/crewkit-setup/templates/skills/`:
+- `full-workflow/SKILL.md` + `full-workflow/references/`
 - `hotfix/SKILL.md`
 - `explore-and-plan/SKILL.md`
 - `review-pr/SKILL.md`
 
-Copy each skill template to `.claude/skills/[name]/SKILL.md`.
+Copy each skill template to `.claude/skills/[name]/SKILL.md`. **If the template has a `references/` subdirectory, copy it too.**
 
 These skill templates are **stack-agnostic** by design — they reference `.ai/memory/commands.md` for build/test commands and `.ai/memory/` for project context. No variable substitution needed.
 
+**Skill design principle — inline vs. references:**
+- **Inline** in SKILL.md: content needed on every invocation (commands, classification tables, return format)
+- **`references/`**: content needed only on certain branches (fix loop policies, stack-specific adapters, error catalogs). The SKILL.md tells the agent WHEN to load each reference.
+- Never extract always-needed content to references — it adds tool calls without benefit.
+
 ---
 
 ### Step 8 — `.claude/QUICKSTART.md` (onboarding guide)

package/skill/templates/agents/coder.md

@@ -47,6 +47,7 @@ If your project uses `.claude/rules/` directory rules, they are loaded automatic
 - Do not create a new file when adding to an existing file achieves the same goal
 - Do not add `TODO` comments — either fix it now or leave it for the plan
 - **NEVER create test files** — test creation is the **tester agent's exclusive responsibility**
+- **NEVER mark phases, tasks, or features as completed** in `napkin.md`, `state.md`, or any memory/status file — only the orchestrator does this, and only after tester PASS + reviewer APPROVED
 
 ## Return Format
 

package/skill/templates/skills/explore-and-plan/SKILL.md

@@ -52,16 +52,29 @@ Use **architect** with explorer findings. Must return:
 
 **The architect must NOT produce the plan.** Only analysis and decisions.
 
-### 3. Present decisions — MANDATORY PAUSE
+### 3. Present decisions — MANDATORY PAUSE (one-by-one)
 
-**DO NOT create the plan yet.** Present to user:
-- Each decision with options, pros/cons, recommendation
-- Required vs compromise vs debt
-- Task size and key risks
-- Technical verdict
-- Ask user to confirm or override each decision
+**DO NOT create the plan yet.**
 
-**Wait for user response.**
+First, present a brief summary: task size, technical verdict, total number of decisions, and key risks. Then present decisions **one at a time**, waiting for user response before showing the next.
+
+**For each decision:**
+1. **Name the decision** clearly (e.g., "D1: How to store the onboarding flag")
+2. **Explain what it solves** — 1-2 sentences so the user understands WHY this decision matters
+3. **Present options as a table** with Pros and Cons columns
+4. **Explain the practical difference** — not abstract architecture, but what concretely changes for the user/system with each option
+5. **State your recommendation** with a clear prompt (e.g., "Go with A?")
+6. **Wait for the user to respond** before presenting the next decision
+
+**Rules:**
+- ONE decision per message. Never batch multiple decisions.
+- If the user agrees, confirm and move to the next immediately.
+- If the user disagrees, acknowledge the override and record it. Then move to the next.
+- If the user asks for more detail, explain further before asking again.
+- After ALL decisions are confirmed, show a complete summary table.
+- If scope is large, ask about scope reduction early (D1 or D2) since it affects all subsequent decisions.
+
+**Wait for ALL decisions to be resolved before proceeding to step 4.**
 
 ### 4. Create plan file (after confirmation)
 

package/skill/templates/skills/full-workflow/SKILL.md

@@ -121,81 +121,11 @@ If a durable lesson was learned, append to the appropriate `lessons-{domain}.md`
 
 ---
 
-# Part 2 — Operational Policies
-
-## Exit gate
-
-**HARD BLOCK: No task is complete without reviewer APPROVED (clean).**
-
-- Tester PASS alone is **not sufficient**
-- Reviewer APPROVED is **mandatory** before Summarize
-- **APPROVED with IMPORTANT+ findings is NOT clean.** Fix, then re-run tester + reviewer.
-- Both must be clean (PASS + APPROVED without IMPORTANT+ findings) before Summarize.
-
-## Findings consolidation
-
-After tester and reviewer finish:
-
-1. **Collect** results from both
-2. **Classify:** Tester = PASS/FAIL. Reviewer = APPROVED/NEEDS_CHANGES
-3. **Deduplicate** — same file + same concern → keep higher severity
-4. **APPROVED with IMPORTANT+ findings** = treat as NEEDS_CHANGES
-5. **Decision matrix:**
-
-| Tester | Reviewer | Action |
-|--------|----------|--------|
-| PASS | APPROVED (clean) | Done → Summarize |
-| PASS | APPROVED with IMPORTANT+ | Fix loop |
-| PASS | NEEDS_CHANGES | Fix loop (reviewer findings) |
-| FAIL | APPROVED | Fix loop (test failures) |
-| FAIL | NEEDS_CHANGES | Fix loop (merge into ONE list for coder) |
-
-When both fail, call coder **once** with the merged list.
-
-## Fix loop
-
-1. **Fix:**
-   - Risk **HIGH**: all fixes through **coder** — never auto-fix
-   - Risk LOW/MEDIUM: `auto_fixable: yes` → orchestrator applies directly. Else → coder
-   - When fix changes an exception type or interface → instruct coder to grep for all test doubles/fakes
-2. **Revalidate in parallel** (tester fix-loop mode + reviewer)
-3. Consolidate again
-4. Exit when PASS + APPROVED
-5. **Max 5 iterations** — then STOP and report to user.
-
-**MINOR findings** do not trigger fix loop alone.
-
-**Tester time budget:** if the tester reports pre-existing failures unrelated to the current task, the orchestrator must NOT ask the tester to fix them. Note them for a separate task and proceed.
-
-## Test creation rule
-
-**Every behavioral change must be validated by tests.** The tester creates them automatically.
-
-- New feature with logic → unit tests + integration when applicable
-- Bug fix → test that reproduces the bug + verifies the fix
-- Refactor with preserved behavior → existing tests are sufficient
-- Cosmetic/text/DTO change without logic → build + review is sufficient
-
-## HIGH risk rules
-
-- Never auto-fix — all through coder
-- Full test suite on every revalidation
-- Reviewer always mandatory
-- Architect mandatory if any design decision is open
-
-## Stop conditions
-
-STOP and escalate when:
-- Build doesn't stabilize after 2 corrections
-- Reviewer flags an architectural problem
-- Tester finds widespread failures outside task scope
-- Root cause unclear after 1 fix loop
-- Affected files grow beyond plan
-- SMALL/MEDIUM reveals structural impact
+> **Operational policies** (exit gate, fix loop, findings consolidation, stop conditions): load `references/operational-policies.md` when entering consolidation or fix loop.
 
 ---
 
-# Part 3 — Stack Configuration
+# Part 2 — Stack Configuration
 
 The orchestrator must tell subagents which build/test commands to use. Read `.ai/memory/commands.md` at the start and use the correct commands for each stack.
 

package/skill/templates/skills/full-workflow/references/operational-policies.md

@@ -0,0 +1,85 @@
+# Full-Workflow — Operational Policies
+
+Referenced by `SKILL.md`. Load when entering consolidation, fix loop, or stop conditions.
+
+---
+
+## Exit gate
+
+**HARD BLOCK: No task is complete without reviewer APPROVED (clean).**
+
+- Tester PASS alone is **not sufficient**
+- Reviewer APPROVED is **mandatory** before Summarize
+- **APPROVED with IMPORTANT+ findings is NOT clean.** Fix, then re-run tester + reviewer.
+- Both must be clean (PASS + APPROVED without IMPORTANT+ findings) before Summarize.
+
+---
+
+## Findings consolidation
+
+After tester and reviewer finish:
+
+1. **Collect** results from both
+2. **Classify:** Tester = PASS/FAIL. Reviewer = APPROVED/NEEDS_CHANGES
+3. **Deduplicate** — same file + same concern → keep higher severity
+4. **APPROVED with IMPORTANT+ findings** = treat as NEEDS_CHANGES
+5. **Decision matrix:**
+
+| Tester | Reviewer | Action |
+|--------|----------|--------|
+| PASS | APPROVED (clean) | Done → Summarize |
+| PASS | APPROVED with IMPORTANT+ | Fix loop |
+| PASS | NEEDS_CHANGES | Fix loop (reviewer findings) |
+| FAIL | APPROVED | Fix loop (test failures) |
+| FAIL | NEEDS_CHANGES | Fix loop (merge into ONE list for coder) |
+
+When both fail, call coder **once** with the merged list.
+
+---
+
+## Fix loop
+
+1. **Fix:**
+   - Risk **HIGH**: all fixes through **coder** — never auto-fix
+   - Risk LOW/MEDIUM: `auto_fixable: yes` → orchestrator applies directly. Else → coder
+   - When fix changes an exception type or interface → instruct coder to grep for all test doubles/fakes
+2. **Revalidate in parallel** (tester fix-loop mode + reviewer)
+3. Consolidate again
+4. Exit when PASS + APPROVED
+5. **Max 5 iterations** — then STOP and report to user.
+
+**MINOR findings** do not trigger fix loop alone.
+
+**Tester time budget:** if the tester reports pre-existing failures unrelated to the current task, the orchestrator must NOT ask the tester to fix them. Note them for a separate task and proceed.
+
+---
+
+## Test creation rule
+
+**Every behavioral change must be validated by tests.** The tester creates them automatically.
+
+- New feature with logic → unit tests + integration when applicable
+- Bug fix → test that reproduces the bug + verifies the fix
+- Refactor with preserved behavior → existing tests are sufficient
+- Cosmetic/text/DTO change without logic → build + review is sufficient
+
+---
+
+## HIGH risk rules
+
+- Never auto-fix — all through coder
+- Full test suite on every revalidation
+- Reviewer always mandatory
+- Architect mandatory if any design decision is open
+
+---
+
+## Stop conditions
+
+STOP and escalate when:
+- Build doesn't stabilize after 2 corrections
+- Reviewer flags an architectural problem
+- Tester finds widespread failures outside task scope
+- Root cause unclear after 1 fix loop
+- Affected files grow beyond plan
+- SMALL/MEDIUM reveals structural impact