@oyolincc/create 0.5.0 → 0.5.1

package/templates/monorepo/.agents/skills/plan-using-agent-skills/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: plan-using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Don't know what you want yet? ──────→ ask-grilling
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── No quality bar written down? ──→ spec-constraint-driven-development
+    ├── Have a spec, need tasks? ──────→ plan-planning-and-task-breakdown
+    ├── Implementing code? ────────────→ build-incremental-implementation
+    │   ├── UI prototype exploration? ─→ plan-prototype
+    │   ├── API work? ────────────────→ build-api-and-interface-design
+    │   ├── Need better context? ─────→ build-context-engineering
+    │   └── Stakes high / unfamiliar code? ──→ review-doubt-driven-development
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ test-browser-testing-with-devtools
+    ├── Something broke? ──────────────→ test-debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ review-code-review-and-quality
+    │   ├── Too complex? ─────────────→ simplify-code-simplification
+    │   ├── Security concerns? ───────→ review-security-and-hardening
+    │   └── Performance concerns? ────→ simplify-performance-optimization
+    ├── Committing/branching? ─────────→ ship-git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ship-ci-cd-and-automation
+    ├── Deprecating/migrating? ────────→ ship-deprecation-and-migration
+    ├── Writing docs/ADRs? ───────────→ ship-documentation-and-adrs
+    ├── Adding logs/metrics/alerts? ───→ build-observability-and-instrumentation
+    └── Deploying/launching? ─────────→ ship-shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+Per-skill verification is the local check. The project-wide bar that applies to *every* change, regardless of which skill is active, is the Definition of Done: tests pass, no regressions, behavior verified at runtime, docs updated. See `../../references/definition-of-done.md`. It complements each task's acceptance criteria rather than replacing them.
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `ask-grilling` → `spec-driven-development` → `plan-planning-and-task-breakdown` → `build-incremental-implementation` → `test-driven-development` → `review-code-review-and-quality` → `simplify-code-simplification` → `ship-shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1.  ask-grilling                → Extract what the user actually wants
+3.  spec-driven-development     → Define what we're building
+4.  plan-planning-and-task-breakdown → Break into verifiable chunks
+5.  build-context-engineering         → Load the right context
+7.  build-incremental-implementation  → Build slice by slice
+8.  build-observability-and-instrumentation → Instrument as you build (runs parallel with 7-9, not after)
+9.  review-doubt-driven-development    → Cross-examine non-trivial decisions in-flight
+10. test-driven-development     → Prove each slice works
+11. review-code-review-and-quality     → Review before merge
+12. simplify-code-simplification         → Reduce unnecessary complexity while preserving behavior
+13. ship-git-workflow-and-versioning → Clean commit history
+14. ship-documentation-and-adrs      → Document decisions
+15. ship-deprecation-and-migration   → Retire old systems and move users safely when needed
+16. ship-shipping-and-launch         → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `test-debugging-and-error-recovery` → `test-driven-development` → `review-code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Spec | spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | plan-planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | build-incremental-implementation | Thin vertical slices, test each before expanding |
+| Review | review-doubt-driven-development | Adversarial fresh-context review of every non-trivial decision |
+| Build | build-context-engineering | Right context at the right time |
+| Plan | plan-prototype | UI prototype exploration |
+| Build | build-api-and-interface-design | Stable interfaces with clear contracts |
+| Test | test-driven-development | Failing test first, then make it pass |
+| Test | test-browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Test | test-debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | review-code-review-and-quality | Five-axis review with quality gates |
+| Simplify | simplify-code-simplification | Preserve behavior while reducing unnecessary complexity |
+| Review | review-security-and-hardening | OWASP prevention, input validation, least privilege |
+| Simplify | simplify-performance-optimization | Measure first, optimize only what matters |
+| Ship | ship-git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | ship-ci-cd-and-automation | Automated quality gates on every change |
+| Ship | ship-deprecation-and-migration | Remove old systems and migrate users safely |
+| Ship | ship-documentation-and-adrs | Document the why, not just the what |
+| Build | build-observability-and-instrumentation | Structured logs, RED metrics, traces, symptom-based alerts |
+| Ship | ship-shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |

package/templates/{hono-server/.agents/skills/wayfinder → monorepo/.agents/skills/plan-wayfinder}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: wayfinder
-description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
+name: plan-wayfinder
+description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets in local Markdown files, and resolve them one at a time until the way to the destination is clear.
 disable-model-invocation: true
 ---
 
-A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** on the repo's issue tracker, then works its **decision tickets** — questions whose resolution is a decision, not slices of a build to execute — one at a time until the route is clear.
+A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** in local Markdown files, then works its **decision tickets** — questions whose resolution is a decision, not slices of a build to execute — one at a time until the route is clear.
 
 The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
 
@@ -14,19 +14,26 @@ Wayfinder is **planning** by default: each ticket resolves a decision, and the m
 
 ## Refer by name
 
-Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride _inside_ the name, never stand in for it.
+Every map and ticket has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride _inside_ the name, never stand in for it.
 
 ## The Map
 
-The map is a single issue on this repo's issue tracker, labelled `wayfinder:map` — the canonical artifact. Its tickets are child issues of the map.
+The map is `docs/efforts/<effort>/map.md` — the canonical artifact. Its tickets are separate Markdown files in `docs/efforts/<effort>/issues/`.
 
-The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
+The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links. The map is complete when no open or claimed tickets remain and no in-scope fog remains; report the destination and hand off the decisions.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+### Local storage
+
+This skill defines its own file format; no tracker service or setup skill is required.
+
+- Map: `docs/efforts/<effort>/map.md`.
+- Tickets: `docs/efforts/<effort>/issues/NN-<slug>.md`, numbered from `01`; allocate the next unused number and preserve existing files.
+- Assets: `docs/efforts/<effort>/assets/` for research notes and standalone prototypes. UI prototypes may stay near their host page as `/plan-prototype` specifies; link them from their ticket.
+- Use relative Markdown links between files. A ticket's filename is its stable identity; use its title in human-facing links.
 
 ### The map body
 
-The whole map at low resolution, loaded once per session. Open tickets are **not** listed — they are open child issues, found by query.
+The whole map at low resolution, loaded once per session. Open tickets are **not** listed — find them by reading ticket status and dependencies in `issues/`.
 
 ```markdown
 ## Destination
@@ -39,9 +46,9 @@ The whole map at low resolution, loaded once per session. Open tickets are **not
 
 ## Decisions so far
 
-<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
+<!-- the index — one line per resolved ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
 
-- [<closed ticket title>](link) — <one-line gist of the answer>
+- [<resolved ticket title>](link) — <one-line gist of the answer>
 
 ## Not yet specified
 
@@ -54,29 +61,36 @@ The whole map at low resolution, loaded once per session. Open tickets are **not
 
 ### Tickets
 
-Each ticket is a **child issue** of the map; the tracker's issue id is its identity. Its body is the question, sized to one 100K token agent session:
+Each ticket holds one question sized to one agent session. Its format is:
 
 ```markdown
+# <ticket title>
+
+Type: grilling
+Status: open
+Owner: unassigned
+Blocked by: none
+
 ## Question
 
 <the decision or investigation this ticket resolves>
 ```
 
-Each ticket carries a `wayfinder:<type>` label — one of `research`, `prototype`, `grilling`, `task` (see [Ticket Types](#ticket-types)).
+`Type:` is `research`, `prototype`, `grilling`, or `task`. `Status:` is `open`, `claimed`, `resolved`, or `out-of-scope`. `Blocked by:` lists prerequisite ticket filenames, or `none`.
 
-A session **claims** a ticket by assigning it to the dev driving the map, **first**, before any work, so concurrent sessions skip it. That assignee _is_ the claim: an open, unassigned ticket is unclaimed.
+Claim a ticket before work: set `Status: claimed` and `Owner:` to a unique session identifier. Re-read the file before claiming; skip tickets already claimed by another session. If interrupted, keep the claim until the user requests resumption or reassignment. Plain files provide no atomic cross-session locking; serialize claims and ticket creation when concurrent sessions cannot coordinate.
 
-Blocking uses the tracker's **native** dependency relationship — essential because it renders the frontier _visually_ in the tracker's own UI, so the human sees what's takeable without opening the map. Only a tracker that lacks native blocking falls back to a body convention. A ticket is **unblocked** when every ticket blocking it is closed; the **frontier** is the open, unblocked, unclaimed children — the edge of the known.
+A ticket is unblocked when all its prerequisites are `resolved`. The **frontier** is the open, unblocked tickets, ordered by number. If a prerequisite becomes out of scope, reassess its dependents explicitly rather than silently treating it as resolved.
 
-The answer isn't part of the body — it's recorded on resolution (see [Work through the map](#work-through-the-map)). Assets created while resolving a ticket are linked from the issue, not pasted in.
+On resolution, append an `## Answer` with the decision, rationale, and relative links to sources or assets; set `Status: resolved`. Keep the question and any existing comments intact. Link assets rather than pasting them into the map.
 
 ## Ticket Types
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/research` **subagent**. Use when knowledge outside the current working directory is required.
-- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
-- **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/plan-research` **subagent**. Use when knowledge outside the current working directory is required.
+- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /plan-prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
+- **Grilling** (HITL): Conversation. The default case. Always invoke /ask-grilling, scoped to this ticket’s question. Clarify ambiguous terms that affect the decision and record agreed definitions in the answer. Capture questions outside that scope as new tickets or fog.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
 
 ## Fog of war
@@ -98,7 +112,7 @@ Fog only ever gathers _toward_ the destination. The destination fixes the scope,
 
 Out-of-scope work never graduates — the frontier stops at the destination — so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
 
-Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — **close it** (a closed ticket is unambiguously off the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking the closed ticket. It stays out of **Decisions so far**, which records the route actually walked — a scope boundary isn't a step on it.
+Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — **set its status to `out-of-scope`** (removing it from the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking that ticket. It stays out of **Decisions so far**, which records the route actually walked — a scope boundary isn't a step on it.
 
 ## Invocation
 
@@ -108,21 +122,21 @@ Two modes. Either way, **never resolve more than one ticket per session** — wi
 
 User invokes with a loose idea.
 
-1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
+1. **Name the destination.** Run a `/ask-grilling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
-3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
-4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket.
+3. **Create `map.md`**: Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
+4. **Create the tickets you can specify now** as ticket files — then wire blocking edges in a **second pass** (ticket files must exist before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/plan-research` subagent to resolve it in parallel, saving its cited findings under `assets/` and linking them from its ticket. Claim each research ticket before dispatch; the subagent records its answer and resolved status, while the coordinating session updates the map to avoid concurrent map edits. Git staging and commits require an explicit user request.
 6. Stop — charting is one session's work; it hand-resolves nothing.
 
 ### Work through the map
 
-User invokes with a map (URL or number). A ticket is **optional** — without one, you pick the next decision, not the user.
+User invokes with a map file path. A ticket is **optional** — without one, you pick the next decision, not the user.
 
 1. Load the **map** — the low-res view, not every ticket body.
-2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work.
-3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
-4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
-5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.
+2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: set its status and owner before any work.
+3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use `/ask-grilling` scoped to the current ticket.
+4. Record the resolution: append an `## Answer`, set `Status: resolved`, and **append a context pointer** to the map's Decisions-so-far.
+5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update those tickets or mark them out of scope, preserving their history.
 
-The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.
+The user may run unblocked tickets in parallel, so expect other sessions to be editing the files concurrently; follow the claim and coordination rules above.