guild-agents 0.3.1 → 1.0.0

package/src/templates/skills/build-feature/SKILL.md

@@ -2,6 +2,104 @@
 name: build-feature
 description: "Full pipeline: evaluation -> spec -> implementation -> review -> QA"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: evaluate
+      role: advisor
+      intent: "Evaluate the feature against the project vision. Identify risks, dependencies, and conflicts. Issue verdict: Approved / Rejected / Requires adjustments."
+      requires: [feature-description]
+      produces: [evaluation-report, verdict]
+      model-tier: reasoning
+      on-failure: abort
+    - id: specify
+      role: product-owner
+      intent: "Break the feature into concrete tasks with verifiable acceptance criteria. Estimate effort and suggest implementation order."
+      requires: [feature-description, evaluation-report]
+      produces: [task-list, acceptance-criteria]
+      model-tier: reasoning
+      condition: step.evaluate.verdict != rejected
+    - id: design
+      role: tech-lead
+      intent: "Define implementation approach: files to modify, patterns to follow, interfaces, and technical risks."
+      requires: [task-list, acceptance-criteria]
+      produces: [technical-plan]
+      model-tier: reasoning
+    - id: implement
+      role: developer
+      intent: "Implement the feature following the technical plan. Write unit tests. Make atomic commits."
+      requires: [technical-plan, acceptance-criteria]
+      produces: [implementation, test-results]
+      model-tier: execution
+    - id: gate-pre-review
+      role: system
+      intent: "Run project tests and lint. Both must pass before review."
+      commands: [npm test, npm run lint]
+      gate: true
+      produces: [gate-pre-review-result]
+      on-failure: goto:implement
+    - id: checkpoint-phase4
+      role: system
+      intent: "Create checkpoint commit and write partial pipeline trace (phases 1-4) to spec file."
+      requires: [implementation, gate-pre-review-result]
+      produces: [checkpoint-commit]
+      gate: true
+    - id: review
+      role: code-reviewer
+      intent: "Review code quality, patterns, security, and test coverage. Classify findings as Blocker, Warning, or Suggestion."
+      requires: [implementation, gate-pre-review-result]
+      produces: [review-report]
+      model-tier: reasoning
+      retry:
+        max: 2
+        on: has-blockers
+    - id: fix-review-blockers
+      role: developer
+      intent: "Fix blocker findings from code review. Run tests after fixing."
+      requires: [review-report]
+      produces: [implementation]
+      model-tier: execution
+      condition: step.review.has-blockers
+      on-failure: goto:review
+    - id: qa-phase
+      role: system
+      intent: "Run QA validation with bugfix cycles."
+      delegates-to: qa-cycle
+      requires: [acceptance-criteria, implementation]
+      produces: [qa-report]
+      retry:
+        max: 2
+        on: has-bugs
+    - id: post-qa-review
+      role: code-reviewer
+      intent: "Review changes introduced during QA bugfix cycles."
+      requires: [qa-report, implementation]
+      produces: [post-qa-review-report]
+      model-tier: reasoning
+      condition: step.qa-phase.had-significant-changes
+      retry:
+        max: 2
+        on: has-blockers
+    - id: gate-final
+      role: system
+      intent: "Run project tests and lint as final verification. Both must pass."
+      commands: [npm test, npm run lint]
+      gate: true
+      produces: [final-gate-result]
+      on-failure: goto:qa-phase
+    - id: completion
+      role: system
+      intent: "Write complete pipeline trace to spec file. Update SESSION.md. Present summary to user."
+      requires: [final-gate-result, review-report, qa-report]
+      produces: [pipeline-trace, session-update]
+      gate: true
+    - id: extract-learnings
+      role: learnings-extractor
+      intent: "Extract compound learnings from this pipeline execution."
+      requires: [pipeline-trace]
+      produces: [updated-learnings]
+      model-tier: routine
+      blocking: false
 ---
 
 # Build Feature
@@ -40,27 +138,29 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 At the start of each phase, display a progress indicator to the user before any agent output:
 
 ```text
-[1/6] Advisor — Evaluating feature...
-[2/6] Product Owner — Defining spec...
-[3/6] Tech Lead — Defining technical approach...
-[4/6] Developer — Implementing...
-[5/6] Code Reviewer — Reviewing changes...
-[6/6] QA — Validating acceptance criteria...
+[1/6] Advisor (opus) — Evaluating feature...
+[2/6] Product Owner (opus) — Defining spec...
+[3/6] Tech Lead (opus) — Defining technical approach...
+[4/6] Developer (sonnet) — Implementing...
+[5/6] Code Reviewer (opus) — Reviewing changes...
+[6/6] QA (sonnet) — Validating acceptance criteria...
 ```
 
+Model names are resolved from the step's `model-tier` using the `max` profile: reasoning=opus, execution=sonnet, routine=haiku. System/gate steps do not show a model name.
+
 When a phase loops (review-fix or QA-review cycles), show the iteration:
 
 ```text
-[5/6 · round 2] Code Reviewer — Re-reviewing after fixes...
-[4/6 · round 2] Developer — Fixing review blockers...
+[5/6 · round 2] Code Reviewer (opus) — Re-reviewing after fixes...
+[4/6 · round 2] Developer (sonnet) — Fixing review blockers...
 ```
 
 This indicator MUST be displayed before spawning the agent for that phase.
 
 ### Phase 1 — Evaluation (Advisor)
 
-**Progress:** `[1/6] Advisor — Evaluating feature...`
-**Agent:** Reads `.claude/agents/advisor.md` via Task tool
+**Progress:** `[1/6] Advisor (opus) — Evaluating feature...`
+**Agent:** Reads `.claude/agents/advisor.md` via Task tool with `model: "opus"`
 **Input:** The feature description provided by the user
 **Process:**
 
@@ -74,8 +174,8 @@ This indicator MUST be displayed before spawning the agent for that phase.
 
 ### Phase 2 — Specification (Product Owner)
 
-**Progress:** `[2/6] Product Owner — Defining spec...`
-**Agent:** Reads `.claude/agents/product-owner.md` via Task tool
+**Progress:** `[2/6] Product Owner (opus) — Defining spec...`
+**Agent:** Reads `.claude/agents/product-owner.md` via Task tool with `model: "opus"`
 **Input:** The feature approved by the Advisor + their observations
 **Process:**
 
@@ -88,8 +188,8 @@ This indicator MUST be displayed before spawning the agent for that phase.
 
 ### Phase 3 — Technical Approach (Tech Lead)
 
-**Progress:** `[3/6] Tech Lead — Defining technical approach...`
-**Agent:** Reads `.claude/agents/tech-lead.md` via Task tool
+**Progress:** `[3/6] Tech Lead (opus) — Defining technical approach...`
+**Agent:** Reads `.claude/agents/tech-lead.md` via Task tool with `model: "opus"`
 **Input:** Product Owner tasks + acceptance criteria
 **Process:**
 
@@ -102,8 +202,8 @@ This indicator MUST be displayed before spawning the agent for that phase.
 
 ### Phase 4 — Implementation (Developer)
 
-**Progress:** `[4/6] Developer — Implementing...`
-**Agent:** Reads `.claude/agents/developer.md` via Task tool
+**Progress:** `[4/6] Developer (sonnet) — Implementing...`
+**Agent:** Reads `.claude/agents/developer.md` via Task tool with `model: "sonnet"`
 **Input:** Tech Lead technical plan + PO acceptance criteria
 **Process:**
 
@@ -129,8 +229,8 @@ This gate CANNOT be skipped, even if the user requested phase skipping. The spec
 
 ### Phase 5 — Review (Code Reviewer)
 
-**Progress:** `[5/6] Code Reviewer — Reviewing changes...`
-**Agent:** Reads `.claude/agents/code-reviewer.md` via Task tool
+**Progress:** `[5/6] Code Reviewer (opus) — Reviewing changes...`
+**Agent:** Reads `.claude/agents/code-reviewer.md` via Task tool with `model: "opus"`
 **Input:** The implemented changes (git diff)
 **Process:**
 
@@ -143,7 +243,7 @@ This gate CANNOT be skipped, even if the user requested phase skipping. The spec
 
 ### Phase 6 — QA (delegates to /qa-cycle)
 
-**Progress:** `[6/6] QA — Validating acceptance criteria...`
+**Progress:** `[6/6] QA (sonnet) — Validating acceptance criteria...`
 
 Runs the `/qa-cycle` skill passing the PO acceptance criteria as context. The qa-cycle handles:
 
@@ -334,30 +434,33 @@ Example Task invocation:
 ```text
 Task tool with:
   subagent_type: "general-purpose"
-  prompt: "Read .claude/agents/developer.md and assume that role. Then: [task description]"
+  model: "opus"
+  prompt: "Read .claude/agents/advisor.md and assume that role. Then: [task description]"
 ```
 
+The `model` parameter is resolved from the step's `model-tier`: reasoning→`"opus"`, execution→`"sonnet"`, routine→`"haiku"`. System/gate steps run inline (no Task tool).
+
 ## Example Session
 
 ```text
 User: /build-feature add dark mode toggle to settings page
 
-[1/6] Advisor — Evaluating feature...
+[1/6] Advisor (opus) — Evaluating feature...
   Approved. Low risk, aligns with UX roadmap.
 
-[2/6] Product Owner — Defining spec...
+[2/6] Product Owner (opus) — Defining spec...
   3 tasks defined with acceptance criteria.
 
-[3/6] Tech Lead — Defining technical approach...
+[3/6] Tech Lead (opus) — Defining technical approach...
   Use CSS variables + context provider pattern.
 
-[4/6] Developer — Implementing...
+[4/6] Developer (sonnet) — Implementing...
   Implemented ThemeContext, toggle component, CSS vars.
 
-[5/6] Code Reviewer — Reviewing changes...
+[5/6] Code Reviewer (opus) — Reviewing changes...
   Passed. 1 suggestion (memoize context value).
 
-[6/6] QA — Validating acceptance criteria...
+[6/6] QA (sonnet) — Validating acceptance criteria...
   All 3 acceptance criteria verified. 0 bugs.
 
 Feature complete. PR ready for merge.
@@ -368,3 +471,4 @@ Feature complete. PR ready for merge.
 - If the user wants to skip phases (e.g., "already evaluated, implement directly"), allow skipping to Phase 4 but warn that validation is lost. Verification gates (pre-Review and final) are NEVER skipped
 - The pipeline is sequential: each phase depends on the output of the previous one
 - Review/QA loops have limits to prevent infinite cycles
+- In v1.x, parallel pipeline execution (multiple build-features via worktrees) is best-effort and depends on the host environment supporting concurrent agents

package/src/templates/skills/council/SKILL.md

@@ -2,6 +2,49 @@
 name: council
 description: "Convenes multiple agents to debate an important decision"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: identify-type
+      role: system
+      intent: "Analyze the question and determine council type: architecture, feature-scope, or tech-debt."
+      requires: [user-question]
+      produces: [council-type, participant-roles]
+      gate: true
+    - id: agent-1
+      role: dynamic
+      intent: "Analyze the question from specialized perspective. State position with concrete arguments."
+      requires: [user-question, council-type]
+      produces: [perspective-1]
+      model-tier: reasoning
+      parallel: [agent-2, agent-3]
+    - id: agent-2
+      role: dynamic
+      intent: "Analyze the question from specialized perspective. State position with concrete arguments."
+      requires: [user-question, council-type]
+      produces: [perspective-2]
+      model-tier: reasoning
+      parallel: [agent-1, agent-3]
+    - id: agent-3
+      role: dynamic
+      intent: "Analyze the question from specialized perspective. State position with concrete arguments."
+      requires: [user-question, council-type]
+      produces: [perspective-3]
+      model-tier: reasoning
+      parallel: [agent-1, agent-2]
+    - id: synthesize
+      role: system
+      intent: "Synthesize debate: points of agreement, disagreement, risks. Present options to user."
+      requires: [perspective-1, perspective-2, perspective-3]
+      produces: [synthesis, options]
+      gate: true
+    - id: write-spec
+      role: system
+      intent: "After user decides, write spec document to docs/specs/."
+      requires: [synthesis, user-decision]
+      produces: [spec-document]
+      condition: user-wants-spec
+      gate: true
 ---
 
 # Council
@@ -71,7 +114,7 @@ Analyze the user's question and determine which council type applies:
 
 ### Step 2 — Convene agents
 
-Invoke the 3 corresponding agents IN PARALLEL using Task tool. Each agent:
+Invoke the 3 corresponding agents IN PARALLEL using Task tool with `model: "opus"` (all council agents use reasoning tier). Each agent:
 
 1. Reads their `.claude/agents/[name].md` file to assume their role
 2. Reads `CLAUDE.md` and `SESSION.md` for project context
@@ -147,9 +190,12 @@ Example:
 ```text
 Task tool with:
   subagent_type: "general-purpose"
+  model: "opus"
   prompt: "Read .claude/agents/tech-lead.md and assume that role. Then: [debate question]"
 ```
 
+The `model` parameter is resolved from the step's `model-tier`: all council agents use reasoning→`"opus"`.
+
 ## Example Session
 
 ```text
@@ -157,9 +203,9 @@ User: /council Should we migrate from REST to GraphQL?
 
 Council: Architecture
 
-Tech Lead — Recommends GraphQL for complex queries, keep REST for simple CRUD.
-Advisor — Risk is high mid-project. Suggests incremental adoption.
-Developer — Prefers REST simplicity. GraphQL adds tooling overhead.
+Tech Lead (opus) — Recommends GraphQL for complex queries, keep REST for simple CRUD.
+Advisor (opus) — Risk is high mid-project. Suggests incremental adoption.
+Developer (opus) — Prefers REST simplicity. GraphQL adds tooling overhead.
 
 Consensus: Incremental adoption. New endpoints in GraphQL, existing stay REST.
 ```
@@ -173,3 +219,4 @@ Consensus: Incremental adoption. New endpoints in GraphQL, existing stay REST.
 - After the user decides, always offer to write the spec to `docs/specs/`
 - The spec document is the primary output of `/council` — it captures the debate, decision, and rationale
 - If the user declines the spec, log the decision to SESSION.md as before
+- In v1.x, `parallel` execution is best-effort — the orchestrator may run parallel steps sequentially if concurrent agent execution is unavailable

package/src/templates/skills/create-pr/SKILL.md

@@ -2,6 +2,38 @@
 name: create-pr
 description: "Create a pull request from the current branch with structured summary"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: verify-branch
+      role: system
+      intent: "Verify not on main/develop, check for uncommitted changes, get commits ahead of main."
+      commands: [git branch --show-current, git status, git log main..HEAD --oneline]
+      produces: [branch-name, branch-state, commit-list]
+    - id: gather-context
+      role: system
+      intent: "Collect diff stats, run tests and lint for PR description context."
+      commands: [git diff main..HEAD --stat, npm test, npm run lint]
+      requires: [branch-state]
+      produces: [diff-summary, test-result, lint-result]
+    - id: generate-description
+      role: system
+      intent: "Build structured PR description from commits, diff stats, and test results."
+      requires: [commit-list, diff-summary, test-result, lint-result]
+      produces: [pr-description, pr-title]
+      gate: true
+    - id: create-pr
+      role: system
+      intent: "Push branch to origin and create PR via gh CLI."
+      commands: [git push -u origin, gh pr create]
+      requires: [pr-description, pr-title, branch-name]
+      produces: [pr-url]
+    - id: post-creation
+      role: system
+      intent: "Display PR URL and suggest next steps."
+      requires: [pr-url]
+      produces: [summary]
+      gate: true
 ---
 
 # Create PR

package/src/templates/skills/dev-flow/SKILL.md

@@ -2,6 +2,20 @@
 name: dev-flow
 description: "Shows current pipeline phase and what comes next"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: read-state
+      role: system
+      intent: "Read SESSION.md to determine current feature and pipeline phase."
+      commands: [cat SESSION.md]
+      produces: [session-state, feature-name, current-phase]
+    - id: present-flow
+      role: system
+      intent: "Display pipeline progress with phase checklist and suggest next step."
+      requires: [session-state, feature-name, current-phase]
+      produces: [flow-display]
+      gate: true
 ---
 
 # Dev Flow

package/src/templates/skills/guild-specialize/SKILL.md

@@ -2,6 +2,44 @@
 name: guild-specialize
 description: "Enriches CLAUDE.md by exploring the project and specializes agents to the real stack"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: read-base
+      role: system
+      intent: "Read CLAUDE.md, PROJECT.md, and SESSION.md for current Guild configuration."
+      commands: [cat CLAUDE.md, cat PROJECT.md, cat SESSION.md]
+      produces: [claude-md, project-md, session-md]
+    - id: explore-project
+      role: system
+      intent: "Scan project structure, dependency files, configs, CI, and documentation to detect stack and architecture."
+      commands: [ls -R src/, cat package.json]
+      produces: [detected-stack, detected-architecture, detected-conventions]
+      gate: true
+    - id: enrich-claude-md
+      role: tech-lead
+      intent: "Replace [PENDING: guild-specialize] placeholders in CLAUDE.md with detected project information."
+      requires: [claude-md, detected-stack, detected-architecture, detected-conventions]
+      produces: [enriched-claude-md]
+      model-tier: reasoning
+    - id: specialize-agents
+      role: tech-lead
+      intent: "Add project-specific context to each agent definition in .claude/agents/."
+      requires: [detected-stack, detected-architecture, detected-conventions]
+      produces: [specialized-agents]
+      model-tier: execution
+    - id: confirm
+      role: system
+      intent: "Present summary of detected stack, architecture, and updated agents."
+      requires: [enriched-claude-md, specialized-agents]
+      produces: [specialization-summary]
+      gate: true
+    - id: commit-enrichment
+      role: system
+      intent: "Commit enriched CLAUDE.md and agent files as an atomic commit."
+      commands: [git add CLAUDE.md .claude/agents/*.md, git commit]
+      requires: [enriched-claude-md, specialized-agents]
+      produces: [enrichment-commit]
 ---
 
 # Guild Specialize
@@ -65,7 +103,7 @@ Investigate the real project structure looking for:
 
 ### Step 3 — Enrich CLAUDE.md
 
-Replace all `[PENDING: guild-specialize]` placeholders in CLAUDE.md with real information:
+Invoke the Tech Lead agent using Task tool with `model: "opus"` (reasoning tier) to replace all `[PENDING: guild-specialize]` placeholders in CLAUDE.md with real information:
 
 - **Stack with exact versions**: extracted from dependency files
 - **Folder structure explained**: what each main folder does
@@ -77,7 +115,7 @@ Replace all `[PENDING: guild-specialize]` placeholders in CLAUDE.md with real in
 
 ### Step 4 — Specialize agents
 
-For each agent in `.claude/agents/*.md`, add project-specific context:
+Invoke the Tech Lead agent using Task tool with `model: "sonnet"` (execution tier) to add project-specific context for each agent in `.claude/agents/*.md`:
 
 - **advisor.md**: real project domain, target users
 - **tech-lead.md**: specific stack, detected patterns, architecture decisions
@@ -89,7 +127,9 @@ For each agent in `.claude/agents/*.md`, add project-specific context:
 - **db-migration.md**: ORM, migration tool, current schema (if applicable)
 - **platform-expert.md**: Claude Code version, known permission bugs, hook configuration
 
-Use the `Task` tool to invoke each agent by reading their `.claude/agents/[name].md` if you need a specialized perspective to enrich their configuration.
+Use the `Task` tool with `model: "sonnet"` to invoke each agent by reading their `.claude/agents/[name].md` if you need a specialized perspective to enrich their configuration.
+
+The `model` parameter is resolved from the step's `model-tier`: reasoning→`"opus"`, execution→`"sonnet"`. System/gate steps run inline (no Task tool).
 
 ### Step 5 — Confirm
 
@@ -129,6 +169,7 @@ User: /guild-specialize
 
 Guild Specialize analyzing project...
 
+Tech Lead (opus) — Enriching CLAUDE.md...
 Stack detected:
 - Node.js 20.11.0, TypeScript 5.3.3
 - React 18.2.0, Next.js 14.1.0
@@ -139,6 +180,7 @@ Architecture:
 - API routes in src/app/api/
 - Shared components in src/components/
 
+Tech Lead (sonnet) — Specializing agents...
 Agents updated:
 - developer.md: Specialized for Next.js + TypeScript
 - qa.md: Configured for Vitest + Playwright

package/src/templates/skills/new-feature/SKILL.md

@@ -2,6 +2,39 @@
 name: new-feature
 description: "Creates branch and scaffold for a new feature"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: get-name
+      role: system
+      intent: "Obtain feature name from user input or prompt for it."
+      produces: [feature-name, feature-description]
+      gate: true
+    - id: create-branch
+      role: system
+      intent: "Create feature branch (simple checkout or worktree for parallel execution)."
+      commands: [git checkout -b]
+      requires: [feature-name]
+      produces: [branch-name]
+    - id: update-session
+      role: system
+      intent: "Update SESSION.md with new feature context, date, and state."
+      requires: [feature-name, feature-description, branch-name]
+      produces: [session-update]
+      gate: true
+    - id: create-issue
+      role: system
+      intent: "Optionally create GitHub Issue for the feature via gh CLI."
+      commands: [gh issue create]
+      requires: [feature-name, feature-description]
+      produces: [issue-url]
+      condition: user-wants-issue
+    - id: confirm
+      role: system
+      intent: "Confirm branch created, SESSION.md updated, issue created. Suggest /build-feature."
+      requires: [branch-name, session-update]
+      produces: [confirmation]
+      gate: true
 ---
 
 # New Feature

package/src/templates/skills/qa-cycle/SKILL.md

@@ -2,6 +2,38 @@
 name: qa-cycle
 description: "QA + bugfix cycle until it passes"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: gate-pre-qa
+      role: system
+      intent: "Run project tests and lint before QA validation."
+      commands: [npm test, npm run lint]
+      gate: true
+      produces: [test-result, lint-result]
+    - id: qa-validate
+      role: qa
+      intent: "Validate the implementation against acceptance criteria. Test edge cases and error scenarios. Report bugs found."
+      requires: [acceptance-criteria, test-result, lint-result]
+      produces: [qa-report]
+      model-tier: execution
+      retry:
+        max: 3
+        on: has-bugs
+    - id: bugfix
+      role: bugfix
+      intent: "Diagnose and fix bugs reported by QA. Run tests after fixing."
+      requires: [qa-report]
+      produces: [bugfix-result]
+      model-tier: execution
+      condition: step.qa-validate.has-bugs
+      on-failure: goto:qa-validate
+    - id: gate-post-qa
+      role: system
+      intent: "Run project tests and lint after QA cycle completes."
+      commands: [npm test, npm run lint]
+      gate: true
+      produces: [final-test-result, final-lint-result]
 ---
 
 # QA Cycle
@@ -30,7 +62,7 @@ Before invoking the QA agent, run the project verification commands. The specifi
 
 ### Step 2 — QA Validation
 
-Invoke the QA agent using Task tool:
+Invoke the QA agent using Task tool with `model: "sonnet"` (execution tier):
 
 1. Read `.claude/agents/qa.md` to assume the QA role
 2. Read CLAUDE.md and SESSION.md for context
@@ -42,7 +74,7 @@ Invoke the QA agent using Task tool:
 
 ### Step 3 — Bugfix (if there are bugs)
 
-If QA reports bugs (including test/lint failures), invoke the Bugfix agent using Task tool:
+If QA reports bugs (including test/lint failures), invoke the Bugfix agent using Task tool with `model: "sonnet"` (execution tier):
 
 1. Read `.claude/agents/bugfix.md` to assume the Bugfix role
 2. Receive the QA bug report as input
@@ -71,9 +103,9 @@ Update SESSION.md with the QA cycle result.
 ```text
 User: /qa-cycle
 
-QA Cycle 1: 2 of 5 criteria pass. Bug: form validation missing on email field.
-Bugfix: Added email regex validation to UserForm component.
-QA Cycle 2: 5 of 5 criteria pass. 0 bugs.
+QA (sonnet) — Cycle 1: 2 of 5 criteria pass. Bug: form validation missing on email field.
+Bugfix (sonnet) — Added email regex validation to UserForm component.
+QA (sonnet) — Cycle 2: 5 of 5 criteria pass. 0 bugs.
 
 Result: Approved.
 ```
@@ -81,3 +113,14 @@ Result: Approved.
 ## Subagent Configuration
 
 When spawning QA or Bugfix agents via the Task tool, always use `subagent_type: "general-purpose"`. Guild agent role names are NOT valid Claude Code subagent_types.
+
+Example:
+
+```text
+Task tool with:
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  prompt: "Read .claude/agents/qa.md and assume that role. Then: [task description]"
+```
+
+The `model` parameter is resolved from the step's `model-tier`: qa-validate and bugfix use execution→`"sonnet"`.

package/src/templates/skills/review/SKILL.md

@@ -2,6 +2,26 @@
 name: review
 description: "Standalone code review on the current diff"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: gather-diff
+      role: system
+      intent: "Get current git diff (staged or unstaged) and run tests + lint for context."
+      commands: [git diff --staged, git diff, npm test, npm run lint]
+      produces: [diff-content, test-result, lint-result]
+    - id: review
+      role: code-reviewer
+      intent: "Review code quality, patterns, security, and tests. Classify findings by severity."
+      requires: [diff-content, test-result, lint-result]
+      produces: [review-report]
+      model-tier: reasoning
+    - id: present
+      role: system
+      intent: "Present findings organized by severity with final verdict."
+      requires: [review-report]
+      produces: [formatted-report]
+      gate: true
 ---
 
 # Review
@@ -38,7 +58,7 @@ Note: The Code Reviewer does not have access to Bash (only Read, Glob, Grep), so
 
 ### Step 2 — Invoke Code Reviewer
 
-Invoke the Code Reviewer agent using Task tool:
+Invoke the Code Reviewer agent using Task tool with `model: "opus"` (reasoning tier):
 
 1. Read `.claude/agents/code-reviewer.md` to assume the role
 2. Read CLAUDE.md to understand the project conventions
@@ -66,6 +86,7 @@ If there are blockers, suggest fixing them and running `/review` again.
 User: /review
 
 Reviewing diff: 4 files changed, +127 -34
+Code Reviewer (opus) — Reviewing changes...
 
 Findings:
 - [Warning] src/api/users.js:45 — No input validation on email parameter

package/src/templates/skills/session-end/SKILL.md

@@ -2,6 +2,33 @@
 name: session-end
 description: "Saves current state to SESSION.md"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: gather-state
+      role: system
+      intent: "Analyze current work state: task in progress, pipeline phase, modified files, session commits."
+      commands: [git status, git log --oneline -10]
+      produces: [work-state, modified-files, session-commits]
+    - id: update-session
+      role: system
+      intent: "Write current state, decisions, and next steps to SESSION.md."
+      requires: [work-state, modified-files, session-commits]
+      produces: [session-update]
+      gate: true
+    - id: commit-wip
+      role: system
+      intent: "Create WIP checkpoint commit if uncommitted changes exist."
+      commands: [git add -A, git commit -m "wip: session paused"]
+      requires: [modified-files]
+      produces: [wip-commit]
+      condition: has-uncommitted-changes
+    - id: confirm
+      role: system
+      intent: "Confirm SESSION.md updated, WIP committed, safe to close."
+      requires: [session-update]
+      produces: [confirmation]
+      gate: true
 ---
 
 # Session End