@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.
- package/.phase2s/skills/adversarial/SKILL.md +57 -0
- package/.phase2s/skills/audit/SKILL.md +82 -0
- package/.phase2s/skills/autoplan/SKILL.md +78 -0
- package/.phase2s/skills/careful/SKILL.md +38 -0
- package/.phase2s/skills/checkpoint/SKILL.md +52 -0
- package/.phase2s/skills/consensus-plan/SKILL.md +57 -0
- package/.phase2s/skills/debug/SKILL.md +48 -0
- package/.phase2s/skills/deep-specify/SKILL.md +71 -0
- package/.phase2s/skills/diff/SKILL.md +33 -0
- package/.phase2s/skills/docs/SKILL.md +58 -0
- package/.phase2s/skills/explain/SKILL.md +27 -0
- package/.phase2s/skills/freeze/SKILL.md +37 -0
- package/.phase2s/skills/guard/SKILL.md +38 -0
- package/.phase2s/skills/health/SKILL.md +66 -0
- package/.phase2s/skills/investigate/SKILL.md +50 -0
- package/.phase2s/skills/land-and-deploy/SKILL.md +69 -0
- package/.phase2s/skills/plan/SKILL.md +58 -0
- package/.phase2s/skills/plan-review/SKILL.md +81 -0
- package/.phase2s/skills/qa/SKILL.md +61 -0
- package/.phase2s/skills/remember/SKILL.md +37 -0
- package/.phase2s/skills/retro/SKILL.md +44 -0
- package/.phase2s/skills/review/SKILL.md +42 -0
- package/.phase2s/skills/satori/SKILL.md +44 -0
- package/.phase2s/skills/scope-review/SKILL.md +65 -0
- package/.phase2s/skills/ship/SKILL.md +36 -0
- package/.phase2s/skills/skill/SKILL.md +52 -0
- package/.phase2s/skills/slop-clean/SKILL.md +61 -0
- package/.phase2s/skills/tdd/SKILL.md +49 -0
- package/.phase2s/skills/unfreeze/SKILL.md +20 -0
- package/dist/src/cli/index.js +1 -1
- package/dist/src/mcp/server.d.ts +1 -1
- package/dist/src/mcp/server.js +1 -1
- package/dist/src/skills/loader.d.ts +3 -1
- package/dist/src/skills/loader.d.ts.map +1 -1
- package/dist/src/skills/loader.js +22 -2
- package/dist/src/skills/loader.js.map +1 -1
- 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?"
|