@leing2021/super-pi 0.23.0 → 0.23.2

package/skills/02-plan/references/solution-search.md

@@ -0,0 +1,46 @@
+# Solution Search Strategy
+
+Grep-first strategy for finding relevant solutions before planning or reviewing.
+
+## Steps
+
+1. **Extract keywords** from the task description
+2. **Grep frontmatter** fields (tags, title) in both locations:
+   ```bash
+   grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/
+   ```
+3. **Read frontmatter only** (first 15 lines) of matching files
+4. **Score by:**
+   - Severity match (higher severity = higher priority)
+   - Tag relevance (exact matches rank higher)
+5. **Fully read top 3** candidates
+6. If no matches: report "No relevant solutions found" and proceed
+
+## Search locations
+
+| Level | Path | Use for |
+|---|---|---|
+| Project | `docs/solutions/` | Project-specific learnings |
+| Global | `~/.pi/agent/docs/solutions/` | Cross-project patterns |
+
+## Scoring rubric
+
+| Score | Criteria |
+|---|---|
+| 5 | Exact tag match + high severity + same language |
+| 4 | Tag match + same category |
+| 3 | Partial tag match |
+| 2 | Same category, no tag match |
+| 1 | Worth reading for context |
+| 0 | No relevance |
+
+## Output
+
+- List of relevant solutions with paths and relevance scores
+- Key takeaways from top solutions
+- How they apply to current task
+
+## When to use
+
+- `02-plan`: Before creating implementation units, check for existing patterns
+- `04-review`: Before reviewing, check for known failure modes or solutions

package/skills/03-work/SKILL.md

@@ -5,73 +5,52 @@ description: Execute plan-driven work in a controlled Phase 1 workflow.
 
 # Work
 
-Use this skill when there is a plan path or a tightly scoped bare prompt ready for execution.
+Use this skill when there is a plan path or tightly scoped bare prompt ready for execution.
 
 See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
 
 ## Core rules
 
-- Before execution, load project rules:
-  1. `rules/common/development-workflow.md` and `rules/common/testing.md`
-  2. Detect the project's primary language using [language detection](../references/language-detection.md)
-  3. Load all files in the matching language-specific rules directory (e.g. `rules/typescript/`)
-  4. If the task involves frontend/browser concerns, also load `rules/web/` files
-- Priority: project-level `{repo-root}/rules/` overrides package-level defaults
-- Distinguish between a **plan path** input and a **bare prompt** input before doing work.
-- Prefer deriving execution tasks from plan **implementation units**.
-- Prefer inline execution for small or tightly scoped units.
-- Use **`ce_parallel_subagent`** for independent CE skill-based units that can run concurrently.
-- Use **`ce_subagent`** only for dependent serial chains that benefit from isolated context or specialized CE skill execution.
-- Note: the generic `subagent` / `parallel_subagent` tool names are reserved for third-party agent extensions (e.g. `pi-subagents`); CE skill-router uses the `ce_`-prefixed names to avoid tool-name conflicts.
-- Use **`session_checkpoint`** to track plan execution progress. On start, load the checkpoint and skip completed units. After each unit, save the checkpoint.
-- On execution failure, use `session_checkpoint` `fail` to record the error, then `retry` to get a retry strategy. Follow the suggested strategy to recover.
-- Use **`task_splitter`** to analyze implementation units for file-level dependencies before execution. Run independent units via `ce_parallel_subagent` and dependent units serially.
-- If inside a **worktree** (created via `07-worktree`), execute within it. Otherwise, consider recommending `07-worktree` for isolation.
-- End by recommending `04-review`.
+1. Load project rules (4 steps):
+   - Load `rules/common/development-workflow.md` and `rules/common/testing.md`
+   - Detect project language via [language detection](../references/language-detection.md)
+   - Load matching language-specific rules
+   - If frontend/browser concerns, also load `rules/web/` files
+2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
+3. **Distinguish input:** plan path vs bare prompt
+4. Derive tasks from plan **implementation units**
+5. **Execution mode:**
+   - **Inline mode** for small/scoped units
+   - **`ce_parallel_subagent`** for independent CE skill units
+   - **`ce_subagent`** only for dependent serial chains
+6. Use **`session_checkpoint`** to track progress and enable resume
+7. Use **`task_splitter`** to analyze dependencies before execution
+8. If in **worktree** (via `07-worktree`), execute inside it
+9. End by recommending `04-review`
 
 ## Hard gates — TDD enforcement
 
-Every execution step must follow **RED → GREEN → REFACTOR**:
-- No production code before a verified failing test.
-- No skipping RED or GREEN verification.
-- No completion claim without command output evidence.
-- Evidence before assertions — always.
+Every step follows **RED → GREEN → REFACTOR**:
 
 **Blocking violations** — stop and ask if:
-- code is written before the RED test
-- a RED step fails for the wrong reason
-- missing evidence that the test failed before implementation
-- missing evidence that the test passed after implementation
-- tests added only after code
+- Code written before RED test
+- RED fails for wrong reason
+- Missing evidence test failed before implementation
+- Missing evidence test passed after implementation
+- Tests added only after code
 
 ## Workflow
 
-1. Detect whether the input is a plan path or a bare prompt.
-2. If it is a plan path, read the implementation units and execute from them.
-3. If it is a bare prompt, do a small scope scan before deciding whether to proceed.
-4. Use `session_checkpoint` to load progress and skip completed units.
-5. Use `task_splitter` to identify parallel-safe vs dependent units.
-6. Execute in inline mode by default; use `ce_parallel_subagent` for independent CE skill units and `ce_subagent` only for valuable dependent serial chains.
-7. For each unit, follow strict TDD:
-   a. Run the RED test and confirm expected failure.
-   b. Apply minimal implementation.
-   c. Run the GREEN test and confirm pass.
-   d. Refactor only while tests stay green.
-   e. Run unit-level verification.
-8. Record progress using `references/progress-update-format.md`.
-9. After each unit, save `session_checkpoint`.
-10. On failure, use `session_checkpoint` `fail` then `retry`.
-11. Provide a **completion report** when done.
-12. Hand off to `04-review` using `references/handoff.md`.
-
-## Completion report
-
-When all units are done, provide:
-
-- **Completed units**: list of unit names
-- **Files changed**: all files created or modified
-- **Commands run**: all verification commands executed
-- **Verification results**: pass/fail status for each
-- **Follow-up work**: any remaining risks or open questions
+1. Detect input type (plan path vs bare prompt)
+2. Read implementation units if plan path
+3. Load `session_checkpoint` to skip completed units
+4. Use `task_splitter` for dependency analysis
+5. Execute: **inline mode** by default, `ce_parallel_subagent` for independent units
+6. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
+7. Record progress via `references/progress-update-format.md`
+8. Save `session_checkpoint` after each unit
+9. On failure: `session_checkpoint` `fail` → `retry` → follow strategy
+10. Provide completion report (see `references/completion-report.md`)
+11. Handoff to `04-review` using `references/handoff.md`
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/03-work/references/completion-report.md

@@ -0,0 +1,51 @@
+# Completion Report Template
+
+When all implementation units are complete, provide this report:
+
+## Summary
+
+Brief description of what was completed.
+
+## Completed units
+
+| Unit | Status | Verification |
+|---|---|---|
+| unit-name-1 | ✅ Done | command output |
+| unit-name-2 | ✅ Done | command output |
+
+## Files changed
+
+- Created: `path/to/file`
+- Modified: `path/to/file`
+
+## Commands run
+
+| Command | Result |
+|---|---|
+| `npm test` | ✅ Pass |
+| `npm run build` | ✅ Pass |
+
+## Verification results
+
+All tests pass. Build succeeds. No regressions.
+
+## Follow-up work
+
+- Any remaining risks
+- Open questions
+- Suggested next steps
+
+---
+
+## Report format for skill output
+
+```
+## Completion Report
+
+**Completed:** list of unit names
+**Files changed:** all created/modified files
+**Commands run:** all verification commands
+**Verification:** pass/fail status for each
+
+**Next:** `/skill:04-review`
+```

package/skills/04-review/SKILL.md

@@ -5,78 +5,70 @@ description: "Review code with structured findings. Optional browser QA and regr
 
 # Review
 
-Use this skill after implementation to review changes against the diff, the relevant plan, and prior learnings.
+Use this skill after implementation to review changes against the diff, plan, and prior learnings.
 
 See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
 
 ## Core rules
 
-- Before reviewing, load project rules:
-  1. `rules/common/code-review.md`
-  2. Detect the project's primary language from the changed files using [language detection](../references/language-detection.md)
-  3. Load all files in the matching language-specific rules directory (e.g. `rules/typescript/`)
-  4. If the review involves frontend/browser changes, also load `rules/web/` files
-- Priority: project-level `{repo-root}/rules/` overrides package-level defaults
-- Determine the **diff scope** before selecting reviewers.
-- Use the **`review_router`** tool to automatically select reviewer personas based on diff metadata.
-- Read the relevant **plan** artifact when one exists.
-- Search solutions with grep-first strategy: extract keywords from the task → `bash grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/` → read only frontmatter (first 15 lines) of matching files → score by severity + tag relevance → fully read top 3. Search both project-level (`docs/solutions/`) and global-level (`~/.pi/agent/docs/solutions/`). If no matches, report "No relevant solutions found" and proceed.
-- Produce **structured findings** using `references/findings-schema.md`.
-- When findings are **autofixable**, apply fixes and re-review (max 3 iterations).
-- End with a handoff that can point toward fixes, re-review, or `05-learn`.
-
-## Review discipline — technical evaluation
+1. Load project rules (4 steps):
+   - Load `rules/common/code-review.md`
+   - Detect language from changed files via [language detection](../references/language-detection.md)
+   - Load matching language-specific rules (e.g., `rules/typescript/`)
+   - If frontend/browser changes, also load `rules/web/` files
+2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
+3. Determine **diff scope** before selecting reviewers
+4. Use **`review_router`** tool to select reviewer personas based on diff metadata
+5. Read relevant **plan** artifact when exists
+6. Run solution search (see `references/solution-search.md`):
+   - Extract keywords → `grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/`
+   - Read **frontmatter** only (first 15 lines) of matches → score by severity + tag relevance
+   - Fully read top 3 candidates
+7. Produce structured findings using `references/findings-schema.md`
+8. **Autofixable findings:** apply and re-review (max 3 iterations)
+
+## Review discipline
 
 Code review is **technical evaluation**, not social performance:
-- **Verify before implementing** any suggestion — check against codebase reality.
-- **YAGNI check**: if a suggestion adds a feature nothing uses, question whether it's needed.
-- **No performative agreement** — do not agree with findings without technical verification.
-- **Push back with reasoning** when a finding is technically incorrect for this codebase.
-- **Evidence before assertions** — every finding must cite specific code, not general principles.
+- **Verify before implementing** any suggestion
+- **YAGNI check:** question features nothing uses
+- **No performative agreement:** verify before concurring
+- **Push back** with reasoning when findings are incorrect
+- **Evidence before assertions:** cite specific code, not principles
 
 ## Handling findings
 
-When processing review findings:
-1. **Read** — complete all findings without reacting.
-2. **Verify** — check each finding against codebase reality.
-3. **Evaluate** — is it technically sound for THIS codebase?
-4. **Act** — fix confirmed issues, push back on incorrect ones with reasoning.
-5. **Test** — verify each fix individually, no regressions.
+1. **Read** — complete all findings without reacting
+2. **Verify** — check each against codebase reality
+3. **Evaluate** — is it sound for THIS codebase?
+4. **Act** — fix confirmed issues, push back on incorrect ones
+5. **Test** — verify each fix individually, no regressions
 
 ## Workflow
 
-1. Determine diff scope from the current branch or explicit review target.
-2. Collect diff stats (files changed, insertions, deletions) and call `review_router`.
-3. Read the matching plan artifact when one exists.
-4. Execute the solution search strategy: extract keywords → grep frontmatter fields (tags, title) in `docs/solutions/` and `~/.pi/agent/docs/solutions/` → read frontmatter of candidates only → score and rank → fully read top 3.
-5. Apply each reviewer persona returned by `review_router`.
-6. Merge the results into structured findings.
-7. Verify each finding against the codebase before acting.
-8. If any findings are autofixable, apply fixes, re-run tests, and re-review.
+1. Determine diff scope from branch or explicit target
+2. Collect stats (files, insertions, deletions) → call `review_router`
+3. Read matching plan artifact
+4. Run solution search
+5. Apply each reviewer persona from `review_router`
+6. Merge into structured findings
+7. Verify each finding against codebase
+8. Apply autofixes, re-run tests, re-review if needed
 
 ## Optional: QA Test Mode
 
-After step 8 (code review complete), offer browser-based QA testing:
+After code review complete, offer browser QA:
 
-> Code review complete. Want me to also run the app through browser-based QA?
->
-> - **A) Just code review** — done here
-> - **B) Run browser QA** — use agent-browser to test the live app, find visual/functional bugs
-> - **C) Browser QA + write regression tests** — find bugs, fix them, add regression tests
+> Code review done. Run browser QA?
+> - **A) Done** — stop here
+> - **B) Browser QA** — find visual/functional bugs
+> - **C) QA + regression tests** — find bugs, fix, add tests
 
-If the user picks B or C, read `references/qa-test-mode.md` and execute the QA workflow.
-
-After QA:
-1. Include QA findings in the review handoff alongside code review findings.
-2. If bugs were fixed, note the fix commits.
-3. If regression tests were written, note the test files.
+If B or C: read `references/qa-test-mode.md` and execute workflow.
+After QA: include findings in handoff, note fix commits/test files.
 
 ## Handoff
 
-After review (and optional QA) is complete, hand off using `references/handoff.md`:
-1. Summarize all findings (code review + QA if run).
-2. Note fix commits if any were applied.
-3. Recommend `05-learn` if learnings are worth capturing.
-4. Recommend `03-work` if fixes need further implementation.
+See `references/handoff.md` for format.
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/04-review/references/solution-search.md

@@ -0,0 +1,46 @@
+# Solution Search Strategy
+
+Grep-first strategy for finding relevant solutions before planning or reviewing.
+
+## Steps
+
+1. **Extract keywords** from the task description
+2. **Grep frontmatter** fields (tags, title) in both locations:
+   ```bash
+   grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/
+   ```
+3. **Read frontmatter only** (first 15 lines) of matching files
+4. **Score by:**
+   - Severity match (higher severity = higher priority)
+   - Tag relevance (exact matches rank higher)
+5. **Fully read top 3** candidates
+6. If no matches: report "No relevant solutions found" and proceed
+
+## Search locations
+
+| Level | Path | Use for |
+|---|---|---|
+| Project | `docs/solutions/` | Project-specific learnings |
+| Global | `~/.pi/agent/docs/solutions/` | Cross-project patterns |
+
+## Scoring rubric
+
+| Score | Criteria |
+|---|---|
+| 5 | Exact tag match + high severity + same language |
+| 4 | Tag match + same category |
+| 3 | Partial tag match |
+| 2 | Same category, no tag match |
+| 1 | Worth reading for context |
+| 0 | No relevance |
+
+## Output
+
+- List of relevant solutions with paths and relevance scores
+- Key takeaways from top solutions
+- How they apply to current task
+
+## When to use
+
+- `02-plan`: Before creating implementation units, check for existing patterns
+- `04-review`: Before reviewing, check for known failure modes or solutions

package/skills/06-next/SKILL.md

@@ -9,11 +9,11 @@ Use this skill when the user wants to know what to run next in the Compound Engi
 
 ## Core rules
 
-- Use the `workflow_state` tool to scan repo artifacts before making a recommendation.
-- Use the `session_history` tool to check recent executions and avoid recommending already-completed steps.
+- Use **`workflow_state`** tool to scan repo artifacts before making a recommendation.
+- Use **`session_history`** tool to check recent executions and avoid already-completed steps.
 - Recommend exactly **one** next skill with a clear reason.
 - Do not execute the recommended skill — only suggest it.
-- If the workflow state suggests multiple valid paths, pick the one closest to completing a full loop.
+- If multiple valid paths exist, pick the one closest to completing a full loop.
 
 ## Two modes
 
@@ -21,29 +21,23 @@ Use this skill when the user wants to know what to run next in the Compound Engi
 
 When the user asks "what should I do next?", "continue", or runs `/skill:06-next`:
 
-1. Call `workflow_state` with the repo root.
-2. Apply the recommendation logic from `references/recommendation-logic.md`.
-3. Return:
-   - **Recommended skill name**
-   - **Why** this is the next step
-   - **Brief** summary of current workflow state (1-2 lines)
+1. Call `workflow_state` with the repo root
+2. Apply recommendation logic from `references/recommendation-logic.md`
+3. Return: skill name, reason (1-2 lines), brief workflow state summary
 
 ### Verbose mode: "full status"
 
-When the user asks "show status", "what's the current state", or explicitly requests a detailed report:
+When the user asks "show status", "what's the current state", or uses `--verbose`:
 
-1. Call `workflow_state` with the repo root.
-2. Call `session_history` with `latest` operation to check recent executions.
-3. Return:
-   - Latest relevant brainstorm (path + brief summary)
-   - Latest relevant plan (path + brief summary)
-   - Latest relevant solution (path + brief summary)
-   - Latest runtime artifacts under `.context/compound-engineering/`
-   - Recommended next step with reason
-   - Overall workflow phase summary
+1. Call `workflow_state` with the repo root
+2. Call `session_history` with `latest` operation
+3. Return: latest artifacts (path + summary), status of each phase, recommended next step
 
 ## Artifact locations
 
+See `references/recommendation-logic.md` for full recommendation rules and skill list.
+
+**Quick reference:**
 | Artifact | Path |
 |---|---|
 | Brainstorm | `docs/brainstorms/` |
@@ -51,15 +45,8 @@ When the user asks "show status", "what's the current state", or explicitly requ
 | Solution | `docs/solutions/` |
 | Runtime | `.context/compound-engineering/` |
 
-If `workflow_state` is not available, fall back to `bash` with `ls` and `find` to check which directories and recent files exist, then use `read` on the most relevant recent artifact.
-
-## Available skills
+**Available skills:** `01-brainstorm`, `02-plan`, `03-work`, `04-review`, `05-learn`, `07-worktree`
 
-- `01-brainstorm` — clarify the problem and produce requirements
-- `02-plan` — turn requirements into implementation units
-- `03-work` — execute the plan
-- `04-review` — review changes with structured findings
-- `05-learn` — capture learnings as solution artifacts
-- `07-worktree` — isolated git worktree development
+**Fallback:** If `workflow_state` is unavailable, use `bash ls/find` to check directories, then `read` recent artifacts.
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/06-next/references/recommendation-logic.md

@@ -44,3 +44,48 @@ If brainstorm, plan, and solution all exist:
 If no rule matches cleanly:
 - Summarize the ambiguous state
 - Ask the user what they want to focus on
+
+---
+
+# Skill registry
+
+## Available skills
+
+| Skill | Purpose | When to use |
+|---|---|---|
+| `01-brainstorm` | Clarify problem, produce requirements | Ambiguous request, new idea |
+| `02-plan` | Turn requirements into implementation units | Requirements clear |
+| `03-work` | Execute the plan | Plan ready |
+| `04-review` | Review changes with structured findings | After implementation |
+| `05-learn` | Capture learnings as solution artifacts | After solving a problem |
+| `07-worktree` | Isolated git worktree development | Large/risky/parallel work |
+
+## Artifact locations
+
+| Artifact | Project path | Global path |
+|---|---|---|
+| Brainstorm | `docs/brainstorms/` | — |
+| Plan | `docs/plans/` | — |
+| Solution | `docs/solutions/` | `~/.pi/agent/docs/solutions/` |
+| Handoff | `.context/compound-engineering/handoffs/` | — |
+| Runtime | `.context/compound-engineering/` | — |
+
+## Skill to artifact mapping
+
+When `workflow_state` returns artifacts, map them back to skills:
+
+- Files in `docs/brainstorms/` → produced by `01-brainstorm`
+- Files in `docs/plans/` → produced by `02-plan`
+- Files in `docs/solutions/` → produced by `05-learn`
+- `.context/compound-engineering/` runtime artifacts → produced by `03-work` or `04-review`
+
+## Recommendation priority
+
+When multiple conditions are met, prioritize:
+
+1. `01-brainstorm` — if nothing exists yet
+2. `02-plan` — if brainstorm exists but no plan
+3. `03-work` — if plan exists but no execution
+4. `04-review` — if execution exists but no review
+5. `05-learn` — if review exists but no learning captured
+6. Loop back to `01-brainstorm` or `06-next` for full cycle completion

package/skills/07-worktree/SKILL.md

@@ -5,32 +5,32 @@ description: Create and manage git worktrees for isolated feature development.
 
 # Worktree
 
-Use this skill when you need optional isolated git worktree development for large, risky, or parallel feature work, then merge changes back or clean up after completion.
+Use this skill for optional isolated git worktree development for large, risky, or parallel feature work.
 
 ## Core rules
 
-- Use the `worktree_manager` tool for all git worktree operations.
-- Create a worktree only when the user explicitly asks for isolation, or when the task is large/risky enough and the user confirms.
-- Use a descriptive branch name derived from the plan or task.
-- After creation, report the worktree path so that `03-work` can execute inside it.
-- On completion, offer to merge back and clean up; ask for confirmation before changing the main worktree or deleting branches.
-- Never force operations — if a worktree already exists, report its status instead of creating a duplicate.
+- Use **`worktree_manager`** tool for all operations
+- Only create when user explicitly asks or task is large/risky enough (with confirmation)
+- Derive branch name from plan or task
+- Report worktree path after creation so `03-work` can execute inside it
+- **Never force operations** — if worktree exists, report status instead of duplicating
+- On completion: offer merge → cleanup (with user confirmation)
 
 ## Workflow
 
-1. **Detect**: Use `worktree_manager` with operation `detect` to check if already inside a worktree.
-2. **Create**: When confirmed, use `worktree_manager` with operation `create` to spin up a new worktree with a feature branch.
-3. **Execute**: Run `03-work` inside the worktree directory.
-4. **Merge**: After user confirmation, use `worktree_manager` with operation `merge` to merge the feature branch back to main.
-5. **Cleanup**: After user confirmation, use `worktree_manager` with operation `cleanup` to remove the worktree and delete the branch.
+See `references/worktree-lifecycle.md` for detailed flow, branch naming, and error handling.
 
-## Output
+**Quick reference:**
+1. `detect` — check if already in worktree
+2. `create` — spin up new worktree with feature branch
+3. Execute `03-work` inside worktree directory
+4. `merge` — merge feature branch back (with confirmation)
+5. `cleanup` — remove worktree and delete branch (with confirmation)
 
-After creation, report:
-- Worktree path
-- Branch name
-- Instruction to run `03-work` in the worktree directory
+## Branch naming
 
-After merge, report:
-- Merge result
-- Whether cleanup is recommended
+- `feat/<slug>` — feature work
+- `fix/<slug>` — bug fixes
+- `chore/<slug>` — maintenance tasks
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/08-help/SKILL.md

@@ -7,31 +7,40 @@ description: Explain when to use each Compound Engineering Phase 1 skill and how
 
 Use this skill when the user asks how to use the package, which workflow step comes next, or which Compound Engineering skill fits the current task.
 
-## Phase 1 skill guide
-
-- `01-brainstorm` — use when the request is ambiguous, needs requirements discovery, or the user has a new idea. Three modes: CE requirements discovery (adding features), Startup Diagnostic (YC-style forcing questions for new products/startups), Builder Mode (side projects, hackathons, learning).
-- `02-plan` — use when requirements are clear enough to turn into implementation units. After planning, user can optionally run a CEO-style strategic review or strict review (error maps, failure modes, test diagrams).
-- `03-work` — use when there is a plan or a tightly scoped task ready for controlled execution.
-- `04-review` — use after code changes to produce structured findings. After code review, user can optionally extend to browser-based QA testing (find visual/functional bugs with agent-browser) and regression test generation.
-- `05-learn` — use after solving a problem so the repo gains a durable learning in `docs/solutions/`.
-- `06-next` — use when the user wants to know what to run next, or wants a full status report of the current project state. Default mode recommends one next step; verbose mode (`--verbose` or ask "show status") shows full artifact details.
-
-## Recommended flow
-
-1. Start with `01-brainstorm` when the problem is still fuzzy or you have a new idea.
-   - **Startup founders** get the YC-style diagnostic: demand reality, status quo, narrowest wedge.
-   - **Side project builders** get generative brainstorming: coolest version, fastest path to ship.
-   - **Feature additions** get the standard CE requirements discovery.
-2. Move to `02-plan` once the desired behavior is clear.
-   - Optionally run **CEO Review** to challenge premises, map alternatives, check dream-state alignment.
-   - Or **Strict Review** for full error maps, failure modes, and test diagrams.
-3. Use `03-work` to execute the plan.
-4. Run `04-review` after implementation.
-   - Optionally extend to **Browser QA** for visual and functional bug finding.
-   - Or **Browser QA + Regression Tests** to also generate automated test coverage.
-5. Capture key learnings with `05-learn`.
-6. Use `06-next` at any point to check what to do next, or ask for a full status report.
-
-## Output
-
-When responding, explain the smallest useful next step instead of forcing the full sequence.
+## Core principle
+
+**Explain the smallest useful next step** — do not force the full sequence.
+
+## Trigger conditions
+
+| User asks | Use this skill |
+|---|---|
+| How to use the package | Help with skill selection |
+| Which step comes next | Recommend via workflow state |
+| Which skill fits | Match task to skill |
+
+## Skill mapping
+
+| Skill | When to use |
+|---|---|
+| `01-brainstorm` | Ambiguous request, new idea, requirements discovery |
+| `02-plan` | Requirements clear, turn into implementation units |
+| `03-work` | Plan ready, controlled execution |
+| `04-review` | After code changes, structured findings |
+| `05-learn` | After solving, capture reusable learning |
+| `06-next` | Check status or get next step recommendation |
+| `07-worktree` | Isolated feature development |
+
+## Workflow sequence
+
+See `references/workflow-sequence.md` for detailed flow, mode variants, and output formats.
+
+**Quick reference:**
+1. `01-brainstorm` → clarify problem
+2. `02-plan` → break into units (optional CEO/Strict review)
+3. `03-work` → execute
+4. `04-review` → inspect (optional Browser QA)
+5. `05-learn` → capture learnings
+6. `06-next` → check status anytime
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).