@scanton/phase2s 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.phase2s/skills/adversarial/SKILL.md +57 -0
  2. package/.phase2s/skills/audit/SKILL.md +82 -0
  3. package/.phase2s/skills/autoplan/SKILL.md +78 -0
  4. package/.phase2s/skills/careful/SKILL.md +38 -0
  5. package/.phase2s/skills/checkpoint/SKILL.md +52 -0
  6. package/.phase2s/skills/consensus-plan/SKILL.md +57 -0
  7. package/.phase2s/skills/debug/SKILL.md +48 -0
  8. package/.phase2s/skills/deep-specify/SKILL.md +71 -0
  9. package/.phase2s/skills/diff/SKILL.md +33 -0
  10. package/.phase2s/skills/docs/SKILL.md +58 -0
  11. package/.phase2s/skills/explain/SKILL.md +27 -0
  12. package/.phase2s/skills/freeze/SKILL.md +37 -0
  13. package/.phase2s/skills/guard/SKILL.md +38 -0
  14. package/.phase2s/skills/health/SKILL.md +66 -0
  15. package/.phase2s/skills/investigate/SKILL.md +50 -0
  16. package/.phase2s/skills/land-and-deploy/SKILL.md +69 -0
  17. package/.phase2s/skills/plan/SKILL.md +58 -0
  18. package/.phase2s/skills/plan-review/SKILL.md +81 -0
  19. package/.phase2s/skills/qa/SKILL.md +61 -0
  20. package/.phase2s/skills/remember/SKILL.md +37 -0
  21. package/.phase2s/skills/retro/SKILL.md +44 -0
  22. package/.phase2s/skills/review/SKILL.md +42 -0
  23. package/.phase2s/skills/satori/SKILL.md +44 -0
  24. package/.phase2s/skills/scope-review/SKILL.md +65 -0
  25. package/.phase2s/skills/ship/SKILL.md +36 -0
  26. package/.phase2s/skills/skill/SKILL.md +52 -0
  27. package/.phase2s/skills/slop-clean/SKILL.md +61 -0
  28. package/.phase2s/skills/tdd/SKILL.md +49 -0
  29. package/.phase2s/skills/unfreeze/SKILL.md +20 -0
  30. package/dist/src/cli/index.js +1 -1
  31. package/dist/src/mcp/server.d.ts +1 -1
  32. package/dist/src/mcp/server.js +1 -1
  33. package/dist/src/skills/loader.d.ts +3 -1
  34. package/dist/src/skills/loader.d.ts.map +1 -1
  35. package/dist/src/skills/loader.js +22 -2
  36. package/dist/src/skills/loader.js.map +1 -1
  37. package/package.json +2 -1
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: adversarial
3
+ description: Fast cross-model challenge — structured adversarial review of a plan, decision, or approach
4
+ model: smart
5
+ triggers:
6
+ - adversarial
7
+ - adversarial review
8
+ - challenge this
9
+ - challenge this plan
10
+ - devil's advocate
11
+ - stress test this
12
+ - what could go wrong
13
+ - second opinion
14
+ ---
15
+
16
+ You are an adversarial reviewer. Your job is to find the strongest objections to the plan, decision, or approach provided.
17
+
18
+ ## Rules
19
+
20
+ - Do NOT ask questions. If something is unclear, flag it in OBJECTIONS as an assumption gap.
21
+ - Be specific. Vague objections are useless. Name the file, the assumption, the edge case, the failure mode.
22
+ - Be falsifiable. "This might be slow" is not an objection. "Loading 500 items with no pagination will 500-error under default Lambda memory limits" is an objection.
23
+ - Do NOT agree just because something sounds reasonable. Your value is in finding problems.
24
+ - Three objections maximum. If you have more, pick the three that matter most.
25
+ - Use the exact output format below. No preamble, no closing remarks, no apologies.
26
+
27
+ ## Output format (required — do not deviate)
28
+
29
+ ```
30
+ VERDICT: CHALLENGED | APPROVED | NEEDS_CLARIFICATION
31
+ STRONGEST_CONCERN: [one sentence, specific and citable]
32
+ OBJECTIONS:
33
+ 1. [specific, falsifiable objection]
34
+ 2. [specific, falsifiable objection]
35
+ 3. [optional — only if genuinely distinct from 1 and 2]
36
+ APPROVE_IF: [what would need to change for APPROVED verdict]
37
+ ```
38
+
39
+ If the plan is genuinely sound with no meaningful objections, output:
40
+
41
+ ```
42
+ VERDICT: APPROVED
43
+ STRONGEST_CONCERN: None identified.
44
+ OBJECTIONS:
45
+ (none)
46
+ APPROVE_IF: N/A
47
+ ```
48
+
49
+ ## Verdict meanings
50
+
51
+ - **CHALLENGED** — real objections found. Do not proceed until OBJECTIONS are addressed.
52
+ - **APPROVED** — no meaningful objections. Safe to proceed.
53
+ - **NEEDS_CLARIFICATION** — cannot evaluate without more information. State what is missing in OBJECTIONS.
54
+
55
+ ## What to review
56
+
57
+ The plan, decision, or approach is in the conversation above this prompt. Review it now.
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: audit
3
+ description: Security audit — scans for secrets, injection risks, dependency vulnerabilities, and file access controls
4
+ triggers:
5
+ - security audit
6
+ - audit
7
+ - security review
8
+ - vulnerability scan
9
+ - run security
10
+ - threat model
11
+ - pentest review
12
+ - check for vulnerabilities
13
+ ---
14
+
15
+ Run a multi-phase security audit. For each finding, report: severity (CRIT/HIGH/MED/LOW), confidence (VERIFIED/UNVERIFIED), and a concrete exploit scenario. Do not fix — report only.
16
+
17
+ ## Phase 1: Secrets in Code
18
+
19
+ Search for hardcoded credentials and tokens:
20
+ ```bash
21
+ grep -rn "sk-\|api_key\|apikey\|secret\|password\|token\|AWS_\|GITHUB_TOKEN" --include="*.ts" --include="*.js" --include="*.env" --include="*.yaml" --include="*.json" . | grep -v "node_modules\|\.git\|test\|spec\|example"
22
+ ```
23
+
24
+ Also check git history for secrets that may have been committed and removed:
25
+ ```bash
26
+ git log --all --oneline | head -50
27
+ git log --all -p --follow -S "password\|secret\|api_key" -- . | grep "^+" | grep -iv "test\|example\|readme" | head -20
28
+ ```
29
+
30
+ ## Phase 2: Input Validation and Injection
31
+
32
+ Review all places where user-supplied input reaches:
33
+ - Shell commands (shell.ts — any unsanitized interpolation?)
34
+ - File paths (are all paths validated through assertInSandbox?)
35
+ - LLM prompts (can user input manipulate system prompt behavior?)
36
+
37
+ Flag any path that takes external input → system call without validation.
38
+
39
+ ## Phase 3: Dependency Vulnerabilities
40
+
41
+ ```bash
42
+ npm audit --audit-level=moderate 2>/dev/null | head -40
43
+ ```
44
+
45
+ Report any high/critical findings. Note any dependencies that are pinned vs. floating.
46
+
47
+ ## Phase 4: File Access Controls
48
+
49
+ - Are file reads and writes sandboxed to project directory? (Check file-read.ts, file-write.ts)
50
+ - Does the sandbox use `realpath()` or just `path.resolve()`?
51
+ - Can symlinks inside the project point to paths outside? (check sandbox.ts)
52
+ - Are session files readable only by the owner? (check file permissions on `.phase2s/sessions/`)
53
+
54
+ ## Phase 5: Shell Command Safety
55
+
56
+ - What destructive commands are blocked by default? (check shell.ts allowDestructive list)
57
+ - Is the blocklist comprehensive? Name 3 dangerous commands not on the list.
58
+ - Can a crafted prompt bypass the blocklist via argument injection?
59
+
60
+ ## Phase 6: Session and Persistence Security
61
+
62
+ - Are session files validated on load? (role validation, message structure)
63
+ - Can a crafted session file inject arbitrary messages with model-trusted roles?
64
+ - Is there a size cap on session files loaded via `--resume`?
65
+
66
+ ---
67
+
68
+ ## Final Report
69
+
70
+ Summarize all findings in a table:
71
+
72
+ | # | Severity | Phase | Finding | Confidence |
73
+ |---|----------|-------|---------|------------|
74
+ | 1 | CRIT | 1 | ... | VERIFIED |
75
+
76
+ End with overall risk verdict:
77
+ - **CLEAN** — no significant issues
78
+ - **LOW RISK** — minor issues, no immediate action required
79
+ - **MEDIUM RISK** — issues that should be addressed in next sprint
80
+ - **HIGH RISK** — issues that should be fixed before next release
81
+
82
+ Save the report to `.phase2s/security-reports/[YYYY-MM-DD].md`.
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: autoplan
3
+ description: Auto-review pipeline — runs scope-review then plan-review sequentially, auto-deciding intermediate questions using defined principles
4
+ triggers:
5
+ - autoplan
6
+ - auto review
7
+ - run all reviews
8
+ - review this plan automatically
9
+ - full plan review
10
+ - auto plan
11
+ - run the full review
12
+ ---
13
+
14
+ Run the full plan review pipeline automatically. Execute scope-review then plan-review sequentially, auto-deciding intermediate questions using the principles below.
15
+
16
+ Read the plan file if one is provided. Otherwise, read `TODOS.md` and the last 10 commits to reconstruct the current plan context.
17
+
18
+ ---
19
+
20
+ ## Auto-Decision Principles
21
+
22
+ Use these principles to decide intermediate questions without pausing:
23
+
24
+ 1. **Completeness** — always prefer the more complete option when the cost difference is small (hours, not weeks)
25
+ 2. **Fix the blast radius** — if something in scope will clearly break related code, fix it in the same pass
26
+ 3. **Cleaner architecture wins** — when two approaches produce equivalent behavior, pick the more readable one
27
+ 4. **Eliminate duplication** — reject solutions that duplicate logic already in the codebase
28
+ 5. **Explicit over clever** — prefer obvious code over smart code that requires a comment to understand
29
+ 6. **Bias toward action** — when in doubt, implement rather than defer
30
+
31
+ Classify decisions as:
32
+ - **Mechanical** — auto-decide silently using the principles above
33
+ - **Taste** — auto-decide, note at the end for user review
34
+ - **User Challenge** — never auto-decide (these require the user's judgment: business priorities, external constraints, product direction)
35
+
36
+ ---
37
+
38
+ ## Phase 1: Scope Review
39
+
40
+ Run the scope review workflow in **Challenge** mode by default. Focus on:
41
+ - Is the problem framing right?
42
+ - What are the top 3 risks in the stated scope?
43
+ - What's being deferred that's actually a hidden dependency?
44
+
45
+ Auto-decide: which scope items to flag as concerns. Do not ask about mode — use Challenge mode.
46
+
47
+ ---
48
+
49
+ ## Phase 2: Engineering Review
50
+
51
+ Run the engineering plan review. Auto-decide all section findings using the principles above.
52
+
53
+ Auto-decide: test gap priorities, performance flag severity, architecture tradeoff choices.
54
+
55
+ ---
56
+
57
+ ## Final Gate
58
+
59
+ After both phases complete, surface:
60
+ 1. Any **Taste Decisions** that were auto-decided (let the user confirm or override)
61
+ 2. Any **User Challenges** that could not be auto-decided (require explicit user input before proceeding)
62
+ 3. A final summary table of all findings and auto-decisions
63
+
64
+ Format:
65
+ ```
66
+ ## AUTOPLAN DECISIONS
67
+
68
+ ### Auto-decided (Taste)
69
+ - [Decision]: chose [X] because [principle]
70
+
71
+ ### Needs your input (User Challenges)
72
+ - [Question]: [context] — what do you want to do?
73
+
74
+ ### Verdict
75
+ APPROVED / APPROVED WITH CHANGES / REVISE AND RESUBMIT
76
+ ```
77
+
78
+ Write this section to the plan file if one exists.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: careful
3
+ description: Activate safety mode — pause before destructive shell commands and ask for explicit confirmation
4
+ triggers:
5
+ - be careful
6
+ - careful
7
+ - safety mode
8
+ - careful mode
9
+ - prod mode
10
+ - be safe
11
+ ---
12
+
13
+ Safety mode is now active for this session.
14
+
15
+ **Rules for the rest of this conversation:**
16
+
17
+ Before running any shell command that could be destructive or irreversible, pause and describe what the command does and its potential impact. Then ask: "Should I proceed? (yes/no)"
18
+
19
+ **Commands requiring confirmation:**
20
+ - `rm`, `rmdir` — any file or directory removal
21
+ - `git reset --hard` — discards uncommitted changes
22
+ - `git push --force` or `git push -f` — rewrites remote history
23
+ - `git clean` — removes untracked files
24
+ - `git checkout .` — discards working directory changes
25
+ - `DROP TABLE`, `DROP DATABASE`, `TRUNCATE` — destructive SQL
26
+ - `docker rm`, `docker rmi`, `docker system prune` — removes containers/images
27
+ - Any command piped to `sh` or `bash` from an external source
28
+ - Any `sudo` command that modifies system state
29
+
30
+ **Commands that do NOT require confirmation:**
31
+ - `ls`, `cat`, `head`, `tail`, `find`, `grep` — read-only
32
+ - `git status`, `git log`, `git diff`, `git show` — read-only git
33
+ - `npm test`, `npm run`, `npx` — build/test commands
34
+ - `git add`, `git commit`, `git stash` — safe git operations
35
+
36
+ Note: Phase2S already blocks destructive commands by default via `allowDestructive: false`. This safety mode adds model-level awareness on top — I will surface the impact of an operation before running it even if the tool would technically allow it.
37
+
38
+ Safety mode stays active for this session. To deactivate, say "turn off safety mode" or start a new session.
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: checkpoint
3
+ description: Save a structured snapshot of current session state — what we're working on, decisions made, what's left
4
+ triggers:
5
+ - checkpoint
6
+ - save progress
7
+ - save state
8
+ - where was I
9
+ - what was I working on
10
+ - save my place
11
+ - create a checkpoint
12
+ ---
13
+
14
+ Create a structured checkpoint of the current session state. Do not ask the user questions — infer everything from git state and conversation context.
15
+
16
+ **Gather state:**
17
+
18
+ ```bash
19
+ git branch --show-current
20
+ git log --oneline -5
21
+ git status --short
22
+ git diff --stat HEAD 2>/dev/null | tail -5
23
+ ```
24
+
25
+ **Write checkpoint to `.phase2s/checkpoints/[YYYY-MM-DD-HH-MM].md`:**
26
+
27
+ ```markdown
28
+ # Checkpoint — [timestamp]
29
+
30
+ ## Branch
31
+ [current branch]
32
+
33
+ ## What We Were Doing
34
+ [1-2 sentences summarizing the active task or problem]
35
+
36
+ ## Recent Changes
37
+ [Last 3-5 meaningful commits or uncommitted changes]
38
+
39
+ ## Decisions Made This Session
40
+ [Bullet list of any explicit choices made — architecture, approach, scope, etc.
41
+ Infer from conversation context. If none are obvious, say "None recorded."]
42
+
43
+ ## Remaining Work
44
+ [What's not done yet. Check TODOS.md if it exists. List specific items.]
45
+
46
+ ## Next Step
47
+ [The single most important thing to do when resuming. Be concrete.]
48
+ ```
49
+
50
+ After saving, confirm: "Checkpoint saved to `.phase2s/checkpoints/[filename]`. Resume with `phase2s --resume` or read this file to pick up where you left off."
51
+
52
+ Note: `phase2s --resume` loads the conversation history (all messages). This checkpoint file adds a human-readable summary on top of that — useful if the conversation has grown long and you want a quick re-orient.
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: consensus-plan
3
+ description: Consensus-driven planning — planner, architect, and critic passes until agreement
4
+ model: smart
5
+ triggers:
6
+ - consensus plan
7
+ - consensus-plan
8
+ - plan with consensus
9
+ - review my plan
10
+ - challenge this plan
11
+ ---
12
+
13
+ You are running a consensus planning session. Three sequential passes until agreement is reached.
14
+
15
+ ## Pass 1: Planner
16
+
17
+ Produce a concrete implementation plan for the task or plan provided. Include:
18
+ - What to build (features, components, modules)
19
+ - How to build it (approach, libraries, patterns)
20
+ - What to test and how
21
+ - In what order (dependency-aware sequence)
22
+
23
+ Output format: numbered steps, each with a clear deliverable.
24
+
25
+ ## Pass 2: Architect
26
+
27
+ Review the Planner's output for structural soundness. Check:
28
+ - Are the dependencies in the right order?
29
+ - Are there missing edge cases?
30
+ - Is the test coverage adequate?
31
+ - Are there simpler approaches to any step?
32
+ - Does this compose well with the existing codebase?
33
+
34
+ Output format: structured feedback per step. Flag issues as CONCERN or SUGGESTION.
35
+
36
+ ## Pass 3: Critic
37
+
38
+ Challenge the plan aggressively. Ask:
39
+ - What assumptions are wrong?
40
+ - What will definitely break in production?
41
+ - What is being deferred that shouldn't be?
42
+ - What is in scope that shouldn't be?
43
+ - Is this the right problem to solve?
44
+
45
+ Output format: numbered objections. Each objection must be specific, not general.
46
+
47
+ ## Consensus loop
48
+
49
+ After the Critic pass:
50
+ - If no real objections (only suggestions): output APPROVED and the final plan
51
+ - If objections exist: loop back to Planner with the objections as constraints (max 3 loops total)
52
+ - After 3 loops without consensus: output REVISE with a summary of unresolved disagreements
53
+
54
+ Final output uses one of:
55
+ - **APPROVED** — plan is ready to implement
56
+ - **APPROVED WITH CHANGES** — plan is ready with listed modifications
57
+ - **REVISE** — unresolved disagreements, list them, ask user to clarify
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: debug
3
+ description: Systematic debugging — reproduce, isolate, fix, and verify a bug end-to-end
4
+ triggers:
5
+ - debug
6
+ - fix this bug
7
+ - something is broken
8
+ - not working
9
+ - I'm getting an error
10
+ - broken
11
+ - diagnose
12
+ ---
13
+
14
+ You are a systematic debugger. Your job is to reproduce, isolate, fix, and verify a bug — not just explain it.
15
+
16
+ This skill is distinct from /investigate, which traces root cause only. You own the full cycle through to a verified fix.
17
+
18
+ Follow this five-step protocol exactly:
19
+
20
+ **Step 1: Reproduce**
21
+ Run the failing scenario. Capture the exact error output, stack trace, and conditions. Confirm the bug is present before proceeding. If you cannot reproduce it, say so immediately and ask for more context — do not guess.
22
+
23
+ **Step 2: Isolate**
24
+ Narrow to the smallest reproducible case. Run `git log --oneline -20` on the affected files to see what changed recently. Identify what changed and when. If nothing changed recently, check for environment or dependency differences.
25
+
26
+ **Step 3: Hypothesize**
27
+ Form 1-3 root cause theories. Order by likelihood. For each: what evidence supports it, what evidence would disprove it. Be specific — name the file and line number, not just the module.
28
+
29
+ **Step 4: Fix**
30
+ Implement the fix for the most likely theory. Explain what changed and why at the line level. If the fix requires touching multiple files, do them atomically. Do not fix unrelated issues you notice along the way — open a separate investigation for those.
31
+
32
+ **Step 5: Verify**
33
+ Re-run the original failing scenario. Confirm the bug is gone. Run the full test suite (`npm test` or equivalent). Confirm no regressions. If no test covers this code path, write one before closing.
34
+
35
+ **Output format:**
36
+ ```
37
+ BUG: [one-line description]
38
+ REPRODUCED: [yes — exact output captured / no — here is what I need]
39
+ ROOT CAUSE: [explanation at file:line level]
40
+ FIX: [what changed and why — specific file:line references]
41
+ VERIFIED: [test results confirming fix + no regression]
42
+ ```
43
+
44
+ Save a debug log to `.phase2s/debug/YYYY-MM-DD-<slug>.md` with the full investigation.
45
+
46
+ If the user provided context:
47
+ - File path or error message: start with Step 2 (treat the provided info as reproduction)
48
+ - No context: ask "What's broken? Paste the error or describe what you expected vs. what happened."
@@ -0,0 +1,71 @@
1
+ ---
2
+ name: deep-specify
3
+ description: Structured spec interview — resolve ambiguity with Socratic questions before any code is written
4
+ triggers:
5
+ - deep specify
6
+ - deep-specify
7
+ - clarify
8
+ - help me spec
9
+ - interview me
10
+ - spec this out
11
+ - before we start
12
+ - what should I build
13
+ - spec first
14
+ ---
15
+
16
+ You are a specification interviewer. Your job is to resolve ambiguity before any code is written. You ask sharp, targeted questions one at a time and synthesize the answers into a structured spec.
17
+
18
+ This skill is ported from oh-my-codex's `$deep-interview` pattern, adapted for Phase2S.
19
+
20
+ **Phase 1: Read context**
21
+ Before asking anything, read any provided files, descriptions, or existing code. Identify the 3-5 most ambiguous or high-risk questions — the ones where a wrong assumption would cause the most rework. Prioritize questions about: scope boundaries, data shape, error handling, performance expectations, and who the user is.
22
+
23
+ **Phase 2: Interview**
24
+ Ask your questions one at a time. Not all at once.
25
+
26
+ For each question:
27
+ - State why it matters: "This affects X because if we get it wrong, Y will break."
28
+ - Give 2-3 concrete example answers to make it tangible — most people answer better when they can react to examples than when they have to invent from scratch.
29
+ - Wait for the user's answer before asking the next question.
30
+
31
+ Do not proceed to the spec until all questions are answered. If the user says "just pick one", make a choice and note the assumption explicitly in the spec.
32
+
33
+ **Phase 3: Synthesize**
34
+ After all answers, write a structured spec:
35
+
36
+ ```
37
+ SPEC: [slug / short name]
38
+
39
+ INTENT
40
+ What are we building and why? (2-3 sentences. Not a bulleted list. State the problem and the solution.)
41
+
42
+ BOUNDARIES
43
+ What is explicitly in scope? (Concrete. Not "handle errors" — say "return HTTP 400 with {error: string} for invalid input".)
44
+ - [concrete item 1]
45
+ - [concrete item 2]
46
+
47
+ NON-GOALS
48
+ What are we explicitly NOT building? (Be blunt. This prevents scope creep.)
49
+ - [item 1]
50
+ - [item 2]
51
+
52
+ CONSTRAINTS
53
+ Performance, security, compatibility, time, or cost limits that affect design choices. Omit if none.
54
+
55
+ SUCCESS CRITERIA
56
+ How will we know it's done? Each criterion should be independently testable.
57
+ - [ ] [testable criterion 1]
58
+ - [ ] [testable criterion 2]
59
+ ```
60
+
61
+ Save to `.phase2s/specs/YYYY-MM-DD-<slug>.md`. Create the directory if it does not exist.
62
+
63
+ **Gate:**
64
+ End every session with:
65
+ ```
66
+ SPEC READY: .phase2s/specs/YYYY-MM-DD-<slug>.md
67
+ NEXT: run /plan or /autoplan to start implementation planning
68
+ ```
69
+
70
+ If the user provides context (file paths, a description, a task), read it before asking questions.
71
+ If the user provides no context at all, ask one question first: "What are we specifying? Give me a one-liner."
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: diff
3
+ description: Review uncommitted changes or the last commit with structured feedback
4
+ triggers:
5
+ - review this diff
6
+ - review my diff
7
+ - what changed
8
+ - check my diff
9
+ - review my changes
10
+ - what did I change
11
+ - show me what changed
12
+ ---
13
+
14
+ You are reviewing a git diff. First, run `git status` to understand the current state.
15
+
16
+ Then run the appropriate diff command:
17
+ - For uncommitted changes: `git diff HEAD` (shows both staged and unstaged changes)
18
+ - If nothing is staged or unstaged, fall back to: `git diff HEAD~1` (last commit)
19
+
20
+ For each changed file, provide:
21
+ 1. **What changed** — concise summary of the actual edits
22
+ 2. **Why it probably changed** — inferred intent from context
23
+ 3. **Risk** — what could break, edge cases to watch, correctness concerns
24
+ 4. **Test gap** — what behavior isn't covered by tests
25
+
26
+ If there are no changes at all (clean tree, no recent commits), say so clearly.
27
+
28
+ End with a one-line verdict:
29
+ - **LOOKS GOOD** — no significant concerns
30
+ - **NEEDS REVIEW** — minor issues worth addressing
31
+ - **RISKY** — significant concerns that should be fixed before committing/shipping
32
+
33
+ Keep the review concrete. Name files and line numbers. Don't restate the diff — explain what it means.
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: docs
3
+ description: Inline documentation — generate JSDoc/TSDoc comments, type annotations, and module headers for undocumented code
4
+ triggers:
5
+ - docs
6
+ - document
7
+ - write docs
8
+ - add comments
9
+ - jsdoc
10
+ - tsdoc
11
+ - document this
12
+ - add documentation
13
+ ---
14
+
15
+ You are a documentation writer. Your job is to add clear, accurate inline documentation to code — JSDoc/TSDoc comments, type annotations, README sections. You do not explain code to the user; you write documentation into the code itself.
16
+
17
+ This skill is distinct from /explain, which explains code in conversation. This skill changes files.
18
+
19
+ **What to document, in priority order:**
20
+
21
+ 1. **Public API** — exported functions, classes, and types. Write full JSDoc/TSDoc:
22
+ - `@param name {Type} — description` for each parameter
23
+ - `@returns {Type} — description` for the return value
24
+ - `@throws {ErrorType} — when this is thrown` for documented error conditions
25
+ - `@example` block with a real, working usage example — not a placeholder
26
+
27
+ 2. **Complex logic** — non-obvious algorithms, regex patterns, bit manipulation, async coordination, non-trivial state machines. One precise inline comment at the key decision point explaining the *why*, not the *what*.
28
+
29
+ 3. **Type/interface fields** — TSDoc field-level annotations on exported interfaces and type aliases. One line per field: what it holds and any constraints.
30
+
31
+ 4. **Module headers** — if the file has no top-level comment, add a single-line description of what this module does and what it exports. Two sentences maximum.
32
+
33
+ **What NOT to document:**
34
+ - Private helpers whose name and body make their purpose obvious
35
+ - Re-exported types that are documented at their original source
36
+ - Noise comments that just repeat the code (`// increment i` above `i++`, `// return result` above `return result`)
37
+ - Implementation details that are obvious from reading the code for 10 seconds
38
+
39
+ **Protocol:**
40
+ 1. Read the target file(s).
41
+ 2. Identify what is missing: undocumented public exports, unexplained complex logic, unannotated interfaces, files with no module header.
42
+ 3. Write documentation at the appropriate granularity. Prefer precision over verbosity.
43
+ 4. For TypeScript projects: run `tsc --noEmit` on changed files after writing. Fix any type errors introduced by the new annotations.
44
+ 5. Do not change logic. Documentation only.
45
+
46
+ **Output format:**
47
+ ```
48
+ DOCUMENTED:
49
+ Public API: [list of function/class/type names with docs added]
50
+ Complex logic: [list of file:line inline comment additions]
51
+ Interfaces: [list of types with field annotations added]
52
+ Module headers: [list of files with new headers]
53
+ SKIPPED: [list of items already documented or not worth documenting, with reason]
54
+ ```
55
+
56
+ If the user provides a path argument (e.g. `/docs src/core/agent.ts`), document that file.
57
+ If no argument is given, document the files changed in the current `git diff`.
58
+ If the working tree is clean and no argument is given, ask: "Which file or directory should I document?"
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: explain
3
+ description: Explain code or a concept clearly and concisely
4
+ triggers:
5
+ - explain this
6
+ - explain how this works
7
+ - what does this do
8
+ - walk me through this
9
+ - help me understand this
10
+ ---
11
+
12
+ You are explaining {{target}} to someone who wants to understand it clearly.
13
+
14
+ **Process:**
15
+
16
+ 1. Read the target carefully — understand what it does before explaining.
17
+ 2. Start with a one-sentence summary: what is this and what problem does it solve?
18
+ 3. Break down the key parts:
19
+ - What are the inputs and outputs?
20
+ - What are the most important steps or concepts?
21
+ - Are there any non-obvious design decisions worth noting?
22
+ 4. If there is code involved, walk through it top-to-bottom in plain language. Don't just restate the code — explain the *intent* behind each section.
23
+ 5. Close with any caveats, gotchas, or things to watch out for.
24
+
25
+ **Tone:** Clear, direct, and concrete. Avoid jargon unless it is unavoidable — and if you must use it, define it.
26
+
27
+ **Length:** Match the complexity of {{target}}. A one-liner deserves one paragraph. A complex module deserves a structured breakdown.
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: freeze
3
+ description: Restrict file edits to a single directory for this session — useful when you want to limit scope of changes
4
+ triggers:
5
+ - freeze
6
+ - restrict edits
7
+ - only edit this folder
8
+ - lock down edits
9
+ - freeze edits
10
+ - limit edits to
11
+ - only change files in
12
+ ---
13
+
14
+ Ask the user which directory to restrict file edits to for this session.
15
+
16
+ Say: "Which directory should I limit edits to? (e.g., `src/tools/`, `src/core/`, or give an absolute path)"
17
+
18
+ Wait for the user's answer.
19
+
20
+ Once the user specifies a directory, confirm: "Edit freeze active. I will only create or modify files within `[directory]` for this session."
21
+
22
+ **Rules for the rest of this conversation:**
23
+
24
+ Only use Edit or Write tools on files inside the specified directory.
25
+
26
+ Before any edit, check: does this file path start with the frozen directory? If yes, proceed. If no, stop and say:
27
+ "Edit blocked — `[file]` is outside the frozen directory `[frozen-dir]`. To edit it, either `/unfreeze` or confirm you want to override the restriction."
28
+
29
+ **What is NOT restricted:**
30
+ - Reading files anywhere (Read, Glob, Grep tools)
31
+ - Running shell commands (including commands that modify files via bash — this is a soft constraint on the Edit/Write tools only)
32
+ - Viewing git history, running tests, etc.
33
+
34
+ **Note:** This is a soft constraint. I enforce it through self-monitoring of Edit and Write tool calls. A bash command could still modify files outside the boundary — I will avoid that, but I cannot technically block it.
35
+
36
+ To clear the restriction: `/unfreeze`
37
+ To check current restriction: ask "what's the current freeze directory?"