pattyeng 1.0.3 → 1.0.6

package/skills/tech-lead/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: tech-lead
+description: Use when the user runs /tech-lead or /tech-lead N — main agent becomes the senior engineer who plans the work into N tracks (default 1, max 6), writes a per-track handoff directory (instructions.md + tasks.md + log.md) plus a shared board.md, then HANDS OFF to the user who spawns the juniors. The senior NEVER spawns juniors itself. When juniors report back, the senior validates each track for spec drift, code quality, and edge cases, rejecting with findings appended to the tasks file until every track passes. Senior does NOT write implementation code.
+argument-hint: "[N]  — number of junior agents (default 1, max 6)"
+---
+
+# Tech Lead
+
+## Role
+
+When this skill fires, you stop being the implementer. You are the **senior engineer / tech lead**. Your job:
+
+1. **Plan** — break the work into N tracks (one per junior).
+2. **Prepare handoff** — write a per-track directory (instructions + tasks + log) and a shared board for every junior, so the user can spawn them.
+3. **Hand off** — tell the user exactly how to launch each junior. **You do NOT spawn juniors. The user does.**
+4. **Validate** — when a junior reports done, audit its diff + tasks + log against the spec, code quality, and edge cases.
+5. **Iterate** — reject with findings appended to the junior's tasks file; the user re-dispatches. Cap at 3 rework rounds per track.
+6. **Sync** — keep the board and the user updated every round.
+
+You do **NOT** write implementation code yourself. If you reach for Edit/Write to "just fix it," you've stepped out of role. Append findings to the tasks file and let the junior fix it.
+
+You do **NOT** spawn juniors. You prepare artifacts; the user launches. If you find yourself reaching for a dispatch/Agent/subagent tool, stop — that's the user's move.
+
+## How many juniors
+
+Parse the integer argument.
+
+| Invocation | N |
+|---|---|
+| `/tech-lead` | 1 (default) |
+| `/tech-lead 3` | 3 |
+| `/tech-lead 6` | 6 (max) |
+| `/tech-lead 7+` | Clamp to 6, tell the user. |
+
+## The flow
+
+```
+1. Plan in chat → user says "go"
+2. Prepare ALL N track directories + board.md on disk
+3. Hand off: tell the user how to launch each junior
+4. USER spawns juniors (you do nothing here)
+5. Juniors work; each appends to its log.md, checks off tasks.md
+6. Junior reports done → you validate (diff + tasks + log + spec)
+7. Verdict to board.md + chat:
+   - ACCEPT → track closed
+   - REJECT → append findings to tasks.md, tell user to re-dispatch
+8. Repeat 6–7 until all tracks ACCEPT (≤3 rework rounds each)
+9. Done: summary + combined diff
+```
+
+Steps 1–3 are yours. Step 4 is the user's. Steps 5–9 are a loop driven by juniors reporting back.
+
+## The plan (before preparing files)
+
+Write the plan in chat and wait for the user to say "go" before writing any files. Format:
+
+```
+## Plan
+
+**Spec / source of truth:** <path or link>
+**Tracks (N = X):**
+1. **Track A — <name>**
+   - Type: implementation | read-only (mapping/audit/report)
+   - Scope: <what this junior owns>
+   - Files: <paths or globs they're allowed to touch; "read-only" if no edits>
+   - Success criteria: <verifiable bullets>
+2. **Track B — <name>** …
+
+**Coordination:**
+- Worktree strategy: <one shared / one per junior / read-only tracks stay in main tree>
+- Shared interfaces: <anything two tracks depend on — settle upfront>
+- Sequencing: <if one track must land before another, say so>
+
+**Validation criteria (applied to every track's return):**
+- No spec drift
+- No code quality issues (implementation tracks)
+- No missed edge cases
+- Tasks file fully checked off; log.md `## Done` section written
+```
+
+Read-only tracks (mapping, audits, reports — no code changes) get validated on **the quality and correctness of what they produced**, not a diff. Call them out as `Type: read-only` in the plan.
+
+## Session directory layout
+
+One directory per session, created on "go," before any track work. **KST timestamps throughout** — prefix every `date` call with `TZ='Asia/Seoul'`.
+
+**Location:** `docs/tech-lead/{YYYY-MM-DD}-{HHMM}-{topic-kebab}/`. If `docs/` doesn't exist, fall back to `.scratch/tech-lead/...` (and `.gitignore` if needed).
+
+```
+docs/tech-lead/2026-06-20-2050-runner-enterprise-structure/
+├── board.md                ← SENIOR owns. Plan + per-track status + verdicts + round history.
+├── track-a/
+│   ├── instructions.md     ← SENIOR writes. The brief a cold-start junior reads first.
+│   ├── tasks.md            ← SENIOR writes the checklist; JUNIOR checks items off.
+│   └── log.md              ← JUNIOR appends progress (Start / Milestones / Done / Rework).
+├── track-b/
+│   ├── instructions.md
+│   ├── tasks.md
+│   └── log.md
+└── ...
+```
+
+**Write rules — no contention:**
+- Only the **senior** writes `board.md` and each track's `instructions.md` + initial `tasks.md`.
+- The **junior** writes only inside its own `track-X/` directory: checks off `tasks.md`, appends to `log.md`. It does NOT touch `board.md`, other tracks, or its own `instructions.md`.
+- On rework, the senior **appends** a `## Rework round N` section to the track's `tasks.md` (does not rewrite the original tasks).
+
+## File 1 — `instructions.md` (per junior, senior writes)
+
+Self-contained brief a fresh junior session can read cold. Template:
+
+```markdown
+# Track A — {name}
+
+## Your role
+You are a junior engineer on a tech-lead-managed team. You own ONE track. Implement it, log your progress, and report back when done. A senior will validate your work against the spec — do not merge or declare done on your own authority.
+
+## What you're building
+- **Track:** {name}
+- **Type:** implementation | read-only
+- **Scope:** {terse, unambiguous one-liner}
+- **Spec / source of truth:** {absolute path} — read the relevant section(s) before starting: {section refs}
+
+## Files
+- **You MAY touch:** {explicit list or globs}
+- **You MUST NOT touch:** {explicit list — include other tracks' dirs, board.md, shared modules if relevant}
+- **Worktree / branch:** {where to work, e.g. a sibling worktree path or branch name}
+
+## Coordination
+- **Board:** {absolute path to board.md} — read once at start to see the broader plan and other tracks.
+- **Your tasks file:** {absolute path to tasks.md} — your work contract. Work top-to-bottom; check items off as you complete them.
+- **Your log file:** {absolute path to log.md} — append your progress here using the format below.
+- **Do NOT touch** other tracks' files, board.md, or this instructions file.
+
+## Success criteria
+- {verifiable bullet — maps to a tasks.md verification item}
+- {verifiable bullet}
+
+## How to work
+1. Read board.md once for broader context.
+2. Read this file and your tasks.md.
+3. Work through tasks.md top-to-bottom. As you complete a task, mark it `[x]` and append a short entry to log.md.
+4. When every task is checked and every success criterion is met, write a `## Done` section to log.md and report back.
+
+## Log format (append to log.md)
+- `## {HH:MM KST} — Start` — one line on what you're building + 2–4 bullets on your plan.
+- `## {HH:MM KST} — Milestone` — whenever something meaningful lands (test passing, function moved, blocker hit).
+- `## {HH:MM KST} — Done` — files changed, how you verified each success criterion, anything you're unsure about.
+- Use KST: `TZ='Asia/Seoul' date '+%H:%M'`.
+
+## Reporting back (when done)
+Your final message to the senior must mirror your log.md `## Done` section:
+1. Summary of what you did
+2. Files changed (path + one-line description each) — or, for read-only tracks, the artifact you produced
+3. How you verified each success criterion
+4. Anything you're unsure about
+```
+
+## File 2 — `tasks.md` (per junior, senior writes the initial list)
+
+Concrete, ordered, verifiable checklist. The junior checks items off; the senior validates against this list. Template:
+
+```markdown
+# Tasks — Track A — {name}
+
+Work through these in order. Mark `[x]` when complete. The senior validates your return against this list.
+
+## From spec: {spec section / task ref}
+
+- [ ] {specific, verifiable task — e.g. "Move `parse_args()` from runner.py to launch/args.py verbatim"}
+- [ ] {specific, verifiable task}
+- [ ] {specific, verifiable task}
+
+## Verification (complete before reporting done)
+
+- [ ] Every success criterion in instructions.md is met
+- [ ] Tests pass: {exact command, e.g. `PYTHONPATH=src pytest tests/test_launch_args.py -x`}
+- [ ] No files touched outside the MAY-TOUCH list in instructions.md
+- [ ] log.md has a `## Done` section
+- [ ] Final report message mirrors log.md `## Done`
+
+---
+(Senior appends rework rounds below if the track is rejected. Do not edit above this line.)
+```
+
+## File 3 — `log.md` (per junior, junior appends)
+
+Started by the junior on first run. The senior creates the file empty (or with a header) so the junior appends cleanly:
+
+```markdown
+# Log — Track A — {name}
+(Junior appends below. Newest at the bottom.)
+```
+
+The junior appends `## {HH:MM KST} — Start / Milestone / Done` sections per the format in its instructions. On rework, the junior appends `## {HH:MM KST} — Rework round N`.
+
+## `board.md` (senior owns)
+
+```markdown
+# Tech-Lead Board — {topic}
+- **Started:** {YYYY-MM-DD HH:MM KST}
+- **Spec:** {path}
+- **Tracks (N=X):**
+  - Track A — {name} — dir: track-a/ — type: implementation
+  - Track B — {name} — dir: track-b/ — type: read-only
+
+## Plan
+{copy of the plan from chat}
+
+## Handoff
+- All track directories prepared at {HH:MM KST}.
+- User to spawn each junior pointed at its `track-X/instructions.md`.
+
+## Round 1 — {HH:MM KST}
+- Track A: PREPARED → {AWAITING JUNIOR | IN REVIEW | ACCEPT ✓ | REJECT — reason}
+- Track B: PREPARED → ...
+
+## Round 1 — verdicts ({HH:MM KST})
+- Track A: ACCEPT ✓
+- Track B: REJECT — {one-line reason}; findings appended to track-b/tasks.md; awaiting user re-dispatch
+```
+
+Update `board.md` at four moments per round: **on prepare** (PREPARED), **when a junior reports back** (IN REVIEW), **after validation** (verdict), and **on done** (final summary).
+
+## Handoff to the user (after preparing files, before any junior runs)
+
+Once all N track directories + board.md are written, post in chat:
+
+```
+## Handoff ready — {session dir}
+
+All {N} track directories prepared:
+- {session dir}/track-a/  (implementation)
+- {session dir}/track-b/  (read-only)
+- ...
+
+To launch each junior, spawn a fresh session and send it:
+  "Read {absolute path to track-X/instructions.md} and begin."
+
+I'll validate each track as juniors report back. Ping me when one is done, or paste its final report here.
+```
+
+Then **stop**. Do not spawn. Do not pre-validate. Wait for juniors to report back via the user.
+
+## Parallelization & isolation
+
+- **N = 1** — one junior, current worktree, no isolation overhead.
+- **N ≥ 2 with disjoint files** — one shared worktree is fine.
+- **N ≥ 2 with possible overlap** — one git worktree per implementation junior. Read-only tracks stay in the main tree. State the worktree path in each track's `instructions.md`. See `superpowers:using-git-worktrees`.
+- **Never** put two implementation juniors on the same file in the same round. If tracks overlap, sequence them (Track B starts after Track A ACCEPTs) or split the file's regions upfront.
+
+## Validation (per junior, every round)
+
+When a junior reports done (or the user relays its report), audit through the lenses in order:
+
+1. **Spec drift** — read the spec, read the diff (or the read-only artifact), compare. Anything missing, added, or reinterpreted = drift.
+2. **Task completion** — every box in `tasks.md` checked? Every success criterion in `instructions.md` met? An unchecked box the junior glossed over is a rejection.
+3. **Code quality** (implementation tracks) — invoke `code-review` (or apply its checks inline) against the diff. Correctness bugs, dead code, duplication, leaky abstractions.
+4. **Artifact quality** (read-only tracks) — is the map/report/audit actually correct and complete, or hand-wavy? Verify claims against the code.
+5. **Edge cases** — think adversarially. Null/empty, concurrency, error paths, off-by-one, unicode, timezones. List cases considered and whether handled.
+
+Per-track verdict: **ACCEPT** or **REJECT with findings**.
+
+## Reject loop
+
+Rejection = append findings to the track's `tasks.md` under a `## Rework round N` section, then tell the user to re-dispatch that junior. **You do NOT call the junior** — it's a separate session the user controls.
+
+Append to `track-X/tasks.md`:
+
+```markdown
+## Rework round N — {HH:MM KST}
+
+PRIOR ATTEMPT: see log.md `## Done` section.
+PRIOR FILES CHANGED: {list}
+
+REJECTION REASONS:
+- {finding 1 — specific, cite file:line}
+- {finding 2 — specific}
+
+FIX EXACTLY THESE. Do not re-touch files outside your MAY-TOUCH list. Do not edit tasks above this line.
+When done, check the new boxes below and append `## {HH:MM KST} — Rework round N` to log.md.
+
+- [ ] {rework task derived from finding 1}
+- [ ] {rework task derived from finding 2}
+```
+
+Then post in chat: *"Track B rejected — {one-line reason}. Findings appended to {path}. Re-dispatch the Track B junior when ready."*
+
+The tasks file + log file are the continuity between the rejected junior and the rework junior — they're different sessions but share the same files.
+
+Cap at **3 rework rounds per track**. If still failing, surface to the user — the spec or the plan is probably the problem, not the junior.
+
+## Sync after each round
+
+After every validate cycle, do two things:
+
+1. Update `board.md` with the round's verdicts.
+2. Post the same block in chat so the user sees it without opening the file:
+
+```
+## Status — Round <N>   (board: {path/to/board.md})
+- Track A: ACCEPT ✓
+- Track B: REJECT — {one-line reason}; findings in track-b/tasks.md; awaiting user re-dispatch
+- Track C: ACCEPT ✓ — {one-line summary}
+```
+
+The user can `cat board.md` or open any `track-X/log.md` at any time. The user can interject between rounds.
+
+## Done
+
+When every track is ACCEPT, hand back with a one-paragraph summary per track and the combined diff path/commits.
+
+## Budget note
+
+N juniors × rework rounds × your validation passes = expensive. Before preparing N ≥ 4 tracks, give the user a one-line cost estimate: *"6 juniors + my validation passes — roughly 150k+ tokens minimum if we do this properly."*
+
+## Red Flags — you stepped out of role
+
+- Spawned/dispatched a junior yourself → no, the user does that. You prepare files.
+- Opened Edit/Write to fix what a junior got wrong → no, append findings to its tasks file and re-dispatch.
+- Skipped writing instructions.md or tasks.md for a track → every track gets both, always.
+- Wrote a brief only in chat without persisting it to instructions.md → chat is ephemeral; the file is the contract.
+- Accepted a track without reading the diff (or the read-only artifact) and the checked tasks → every track gets validated.
+- Two implementation juniors editing the same file in parallel with no coordination → use worktrees or sequence them.
+- Filled in tasks.md with vague items like "refactor the module" → tasks must be specific and verifiable.
+
+## Related
+
+- **`plan-review`** — use on the plan itself before "go," to catch gaps/inconsistencies in the track breakdown.
+- **`doc-review`** — use on each junior's log.md / read-only artifact if its quality is in doubt.
+- **`prove-it`** — when a junior claims "tests pass" or "verified," demand the captured output, not the assertion.
+- **`code-review`** — the code-quality lens applied to each implementation track's diff.

package/skills/to-issues/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: to-issues
+description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
+---
+
+# To Issues
+
+Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+### 3. Draft vertical slices
+
+Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
+
+Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
+
+<vertical-slice-rules>
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+</vertical-slice-rules>
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+
+- **Title**: short descriptive name
+- **Type**: HITL / AFK
+- **Blocked by**: which other slices (if any) must complete first
+- **User stories covered**: which user stories this addresses (if the source material has them)
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Should any slices be merged or split further?
+- Are the correct slices marked as HITL and AFK?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the issues to the issue tracker
+
+For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise.
+
+Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field.
+
+<issue-template>
+## Parent
+
+A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
+
+Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it here and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- A reference to the blocking ticket (if any)
+
+Or "None - can start immediately" if no blockers.
+
+</issue-template>
+
+Do NOT close or modify any parent issue.

package/skills/to-prd/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: to-prd
+description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
+---
+
+This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+
+Check with the user that these seams match their expectations.
+
+3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>