@scanton/phase2s 0.13.0 → 0.14.0

package/.phase2s/skills/guard/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: guard
+description: Full safety mode — combines careful (destructive command confirmation) and freeze (edit directory restriction)
+triggers:
+  - guard mode
+  - guard
+  - full safety
+  - lock it down
+  - maximum safety
+  - full guard
+---
+
+Activate full guard mode: both destructive command confirmation and edit directory restriction.
+
+**Step 1: Set the edit boundary**
+
+Ask: "Which directory should I limit file edits to? (e.g., `src/tools/`, `.phase2s/skills/`, or give an absolute path)"
+
+Wait for the user's answer. Confirm: "Edit boundary set to `[directory]`."
+
+**Step 2: Activate safety rules**
+
+Both rules are now active for this session:
+
+**Edit restriction:** Only create or modify files inside `[directory]`. Before any Edit or Write tool call, verify the target path is within the boundary. If not, stop and report the violation.
+
+**Destructive command confirmation:** Before running any destructive shell command, pause and describe what it does and its potential impact, then ask "Should I proceed? (yes/no)"
+
+Destructive commands that require confirmation: `rm`, `rmdir`, `git reset --hard`, `git push --force`, `git clean`, `git checkout .`, `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`, `docker rm`, `docker system prune`, `sudo` (state-modifying).
+
+Safe commands that do NOT require confirmation: `ls`, `cat`, `grep`, `find`, `git status`, `git log`, `git diff`, `npm test`, `git add`, `git commit`.
+
+**Note:** This is a soft constraint enforced through model self-monitoring. I cannot technically intercept tool calls. Phase2S's `allowDestructive: false` config provides shell-level enforcement underneath.
+
+Guard mode stays active for this session.
+- To clear edit restriction only: `/unfreeze`
+- To turn off destructive confirmation: say "turn off safety mode"
+- To clear both: start a new session

package/.phase2s/skills/health/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: health
+description: Code quality dashboard — runs type check, tests, and lint, scores the codebase, shows trends
+triggers:
+  - health check
+  - health
+  - code quality
+  - how healthy is the codebase
+  - run all checks
+  - quality score
+  - codebase health
+---
+
+Run a code quality dashboard. Report only — do not fix anything.
+
+**Step 1: Auto-detect tooling**
+
+Check which tools are available for this project:
+```bash
+test -f package.json && echo "node project"
+test -f tsconfig.json && echo "typescript"
+cat package.json 2>/dev/null | grep -E '"test"|"lint"|"typecheck"' | head -10
+```
+
+**Step 2: Run checks**
+
+Run each available check and capture exit code + output:
+
+1. **Tests** — `npm test` or equivalent. Record: pass/fail, test count, any failures.
+2. **Type check** — `npx tsc --noEmit` if TypeScript. Record: error count.
+3. **Lint** — if eslint/biome configured, run it. Record: warning/error count.
+4. **Dead code** — `npx knip` if available, otherwise skip.
+
+**Step 3: Score**
+
+Score on a 0–10 scale using this rubric:
+- Tests: 40% weight (10 = all pass, 0 = none or failing)
+- Type check: 25% weight (10 = zero errors)
+- Lint: 20% weight (10 = zero warnings)
+- Dead code: 15% weight (10 = no unused exports)
+
+If a tool isn't available, redistribute its weight proportionally.
+
+**Step 4: Report**
+
+```
+HEALTH SCORE: X.X / 10
+
+| Check      | Result       | Score |
+|------------|-------------|-------|
+| Tests      | 139/139 pass | 10/10 |
+| Type check | 0 errors     | 10/10 |
+| Lint       | not configured| —    |
+| Dead code  | not available | —    |
+```
+
+Add a one-paragraph interpretation: what does the score tell you? What's the weakest area?
+
+**Step 5: Persist**
+
+Append the score to `.phase2s/health/history.jsonl`:
+```json
+{"date":"YYYY-MM-DD","score":9.2,"tests":"pass","typecheck":"pass","lint":"skip","notes":""}
+```
+
+If 3+ prior entries exist, show the trend (improving / stable / declining).

package/.phase2s/skills/investigate/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: investigate
+description: Debug an error or unexpected behavior — trace it to the root cause with evidence
+triggers:
+  - why is this broken
+  - debug this
+  - investigate
+  - figure out why
+  - 500 error
+  - something is wrong
+---
+
+You are debugging a problem. Work like a detective: follow the evidence, don't guess.
+
+**Process:**
+
+1. Read the error message or problem description carefully. Identify the key signal (error type, stack trace line, wrong output).
+2. Find the relevant source files. Start at the point of failure, then trace backwards through callers.
+3. Form a hypothesis. State it explicitly: "I think the problem is X because Y."
+4. Verify or falsify the hypothesis by reading the code. Look for: null/undefined paths, missing error handling, wrong types, incorrect assumptions about external behavior (APIs, env vars, file paths).
+5. If the first hypothesis is wrong, state that clearly and form a new one.
+
+**Output format:**
+
+---
+
+## Investigation
+
+**Symptom:** [the error or wrong behavior, quoted exactly]
+
+**Root cause:** [one clear sentence — what is actually wrong]
+
+**Evidence:**
+- `filename:line` — [what this line does and why it's relevant]
+- [continue for each piece of evidence]
+
+**Why it breaks:**
+[2-4 sentences explaining the causal chain from root cause to symptom]
+
+**Fix:**
+```
+[exact code change needed — show before/after if helpful]
+```
+
+**Verify with:**
+[the command or test to confirm the fix works]
+
+---
+
+Do not suggest "try restarting" or "clear the cache" without evidence. Trace to the actual line. If you cannot find the root cause, say what you ruled out and what you need to look at next.

package/.phase2s/skills/land-and-deploy/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: land-and-deploy
+description: Push, open a PR, merge it, wait for CI, and verify the deploy landed cleanly
+triggers:
+  - land this
+  - land and deploy
+  - merge and deploy
+  - push and merge
+  - deploy this
+  - merge the PR
+  - land it
+  - ship to production
+  - push and open PR
+---
+
+You are landing code to production. This picks up where `/ship` (commit) leaves off.
+
+**Prerequisites:** `gh` CLI must be installed and authenticated (`gh auth status`). If not available, tell the user and stop.
+
+**Process:**
+
+1. **Check current state.**
+   - Run `git status` to confirm there are no uncommitted changes. If there are, tell the user to run `/ship` first.
+   - Run `git branch --show-current` to get the current branch name.
+   - If on `main` or `master`, warn the user that landing from the default branch directly is unusual. Confirm before proceeding.
+
+2. **Push the branch.**
+   - Run `git push -u origin <branch>` (use `-u` to set upstream if not already set).
+   - If push fails, read the error carefully. A "non-fast-forward" error means the remote branch has diverged — tell the user they need to rebase or merge first. Do not force-push without explicit instruction.
+
+3. **Create or find the PR.**
+   - Run `gh pr view --json number,url,state 2>/dev/null` to check if a PR already exists for this branch.
+   - If a PR already exists and is open, use it. Show the PR URL.
+   - If no PR exists, create one:
+     ```
+     gh pr create --fill
+     ```
+     `--fill` uses the branch name and commit messages to populate the title and body. If the user provided a task description as input to this skill, use it as the PR title with `--title "..."`.
+   - Show the PR URL after creation.
+
+4. **Wait for CI checks to pass.**
+   - Run `gh pr checks --watch` to stream CI status in real time.
+   - If all checks pass, continue.
+   - If any check fails: show which check failed and what the failure output was (run `gh run view <run-id> --log-failed` to get failure details). Tell the user to fix the failure and re-run `/land-and-deploy`. Stop here.
+   - If there are no CI checks configured, note this and continue.
+
+5. **Merge the PR.**
+   - Run `gh pr merge --merge --delete-branch` to merge with a merge commit and delete the remote branch after merge.
+   - If you prefer squash merge, the user can specify: `gh pr merge --squash --delete-branch`.
+   - If the merge fails due to conflicts, tell the user: the branch has conflicts with the base branch. They need to resolve conflicts locally and push again.
+
+6. **Confirm the land.**
+   - Run `git fetch origin` and `git log origin/main..HEAD --oneline 2>/dev/null || git log origin/master..HEAD --oneline 2>/dev/null` to confirm the current branch's commits are now on the default branch.
+   - Show the merged commit hash.
+   - Optionally run `git checkout main && git pull` (or `master`) to bring the local default branch up to date.
+
+7. **Post-merge summary.**
+   Show a clean summary:
+   ```
+   Landed: feat/my-feature → main
+   PR: #42 (https://github.com/owner/repo/pull/42)
+   Merged: abc1234
+   CI: all checks passed
+   Branch deleted: origin/feat/my-feature
+   ```
+
+**If the user has a deploy process** (e.g., a deploy script, a deploy hook that fires on merge, or a platform like Railway/Vercel/Fly), mention that they should verify their deployment separately. Phase2S does not have visibility into post-merge deployment pipelines unless the user adds a deploy step to their project's verify command.
+
+**Stop and report cleanly at each failure point.** Do not attempt to recover from ambiguous situations automatically.

package/.phase2s/skills/plan/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: plan
+description: Create a concrete implementation plan for a feature or task
+triggers:
+  - plan this
+  - how should I build
+  - implementation plan
+  - design this feature
+  - how do I implement
+---
+
+You are a senior engineer creating an implementation plan. Do not start coding yet — plan first.
+
+**Process:**
+
+1. Read the relevant existing code to understand the current architecture. Look at: entry points, data models, existing patterns used in similar features.
+2. Identify the smallest working version (the MVP slice) — what is the minimum that proves the approach works?
+3. Break the work into ordered phases. Each phase should be independently testable.
+4. Call out risks and open questions before they become bugs.
+
+**Output format:**
+
+---
+
+## Implementation Plan
+
+**Goal:** [one sentence — what this does for the user]
+
+**Approach:** [2-3 sentences — the technical strategy and why]
+
+**Files to create or modify:**
+| File | Change |
+|------|--------|
+| `path/to/file.ts` | [what changes and why] |
+
+**Phases:**
+
+### Phase 1 — [name] (MVP)
+- [ ] [specific task]
+- [ ] [specific task]
+*Verify:* [command or check that proves this phase works]
+
+### Phase 2 — [name]
+- [ ] [specific task]
+*Verify:* [command or check]
+
+[continue as needed]
+
+**Risks and open questions:**
+- [risk]: [mitigation]
+- [open question]: [what you need to decide before coding]
+
+**What this does NOT include:**
+[scope boundaries — what is explicitly out of scope for this plan]
+
+---
+
+Be concrete. Name actual files that exist in the project. Show real commands. If something is unclear in the requirements, ask one clarifying question before proceeding.

package/.phase2s/skills/plan-review/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: plan-review
+description: Engineering plan review — scope validation, architecture critique, test coverage map, performance analysis
+triggers:
+  - review the architecture
+  - engineering review
+  - lock in the plan
+  - plan review
+  - review my plan
+  - tech review
+  - technical review
+  - review this plan
+---
+
+Run an engineering plan review in six sections. For each section, raise issues one at a time — don't batch everything into a wall of text.
+
+If the user provides a plan file path, read it first. Otherwise, ask what plan or design to review.
+
+---
+
+## Section 1: Scope Validation
+
+Is this the minimum viable implementation? Challenge:
+- What's the simplest thing that could accomplish the stated goal?
+- What's being built that could be deferred?
+- What's being deferred that should actually be included (hidden dependencies)?
+- Are there existing utilities, patterns, or modules in the codebase that do part of this?
+
+Run `find . -name "*.ts" | xargs grep -l "relevant keywords" 2>/dev/null | head -10` to check what already exists.
+
+## Section 2: Architecture
+
+Evaluate the design:
+- Data flow: how does input become output? Trace the full path.
+- Failure modes: what happens when each external call fails? (network, file system, subprocess)
+- State management: where is mutable state? Is it necessary?
+- Interface contracts: are the types/schemas precise or is there an `any` escape hatch?
+
+Flag any single point of failure or hard-to-test integration point.
+
+## Section 3: Code Quality
+
+Check for:
+- DRY violations — is the same logic duplicated across files?
+- Error handling — are errors wrapped with context or just re-thrown bare?
+- Technical debt being introduced — anything that will need to be revisited?
+- Naming clarity — do function and variable names explain intent?
+
+## Section 4: Test Coverage Map
+
+Draw an ASCII map of codepaths and their test status:
+
+```
+[user input] → [parser] → [tool call] → [result]
+     ✓             ✓           ✓            ?
+                              ↓
+                        [error path]
+                              ?
+```
+
+Mark: ✓ (tested), ? (gap), ✗ (tested wrong / false positive)
+
+Identify the top 3 test gaps that would catch the most real bugs.
+
+## Section 5: Performance
+
+Flag any:
+- N+1 patterns (loop that makes repeated calls)
+- Synchronous I/O in a hot path
+- Unbounded memory growth (accumulating arrays, unclosed streams)
+- Missing timeouts on external calls
+
+Give concrete estimates where possible ("this runs per-turn, so at 50 turns that's N calls").
+
+## Section 6: Outside Voice
+
+Generate one adversarial challenge: what would a skeptical engineer say is the biggest flaw in this plan? Be concrete and specific, not generic. Then offer a response to the challenge.
+
+---
+
+**End of review.** Summarize: total issues found, severity breakdown (blocking / should-fix / consider), recommendation (APPROVE / APPROVE WITH CHANGES / REVISE AND RESUBMIT).

package/.phase2s/skills/qa/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: qa
+description: Quality assurance pass — find bugs, edge cases, and missing error handling in recent changes
+triggers:
+  - test this
+  - find bugs
+  - qa this
+  - does this work
+  - check for edge cases
+  - what could go wrong
+---
+
+You are doing a QA pass on recent code changes. Your job is to find bugs before users do.
+
+**Process:**
+
+1. Run `git diff HEAD~1` (or `git diff HEAD` if uncommitted) to see what changed.
+2. Read the changed files in full — not just the diff. Context matters.
+3. For each changed function or feature, think through:
+   - **Happy path**: does the normal case work?
+   - **Empty/null inputs**: what happens with empty string, null, undefined, 0, []?
+   - **Boundary conditions**: off-by-one errors, max/min values, empty collections
+   - **Error paths**: what happens when a dependency fails, a file doesn't exist, a network call times out?
+   - **Concurrent access**: could two calls race? Is shared state mutated safely?
+   - **User-visible failures**: what does the user see when something goes wrong?
+
+4. Run any existing tests: `npm test` or equivalent. Report failures.
+
+**Output format:**
+
+---
+
+## QA Report
+
+**Changed files reviewed:** [list]
+
+### Bugs found
+
+**[BUG]** `filename:line` — [what breaks and under what condition]
+Reproduce: [exact steps or input that triggers it]
+Impact: [what the user sees / what data is affected]
+
+### Edge cases not handled
+
+**[EDGE]** [scenario] — [what happens currently vs. what should happen]
+
+### Missing test coverage
+
+**[TEST]** [function/behavior] — [what scenario has no test]
+
+### Looks good
+
+[things that are well-handled — be specific]
+
+### Verdict
+
+[one sentence: ship it / fix before shipping / needs more work]
+
+---
+
+Do not suggest tests without first checking if they already exist. Do not flag style issues — this is functional QA only.

package/.phase2s/skills/remember/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: remember
+description: Save a project learning to persistent memory for future sessions
+triggers:
+  - remember this
+  - save this learning
+  - note this for later
+  - add to memory
+  - remember for next time
+  - save to memory
+  - memorize this
+---
+
+Save a specific learning to `.phase2s/memory/learnings.jsonl` so it persists across sessions.
+
+Follow these steps exactly:
+
+1. Ask the user: "What should I remember? Give me one specific insight." Wait for their answer.
+
+2. Ask the user: "What type is this learning? Choose one: preference, decision, pattern, constraint, or tool." Wait for their answer.
+
+3. Construct a JSON object with these fields:
+   - `key`: a short slug (2-4 words, hyphen-separated, lowercase) that identifies the learning
+   - `insight`: the full learning text, exactly as the user stated it (or lightly cleaned up for clarity)
+   - `type`: the type the user chose
+   - `confidence`: 1 (default for user-specified learnings)
+   - `ts`: current ISO 8601 timestamp
+
+4. Append the JSON as a single line to `.phase2s/memory/learnings.jsonl` using the shell tool:
+   ```
+   echo '{"key":"...","insight":"...","type":"...","confidence":1,"ts":"..."}' >> .phase2s/memory/learnings.jsonl
+   ```
+   Use the shell tool with this exact command. Make sure the JSON is on one line. Create the file if it doesn't exist (>> handles this automatically).
+
+5. Confirm to the user: "Saved learning '[key]' to .phase2s/memory/learnings.jsonl. It will be loaded at the start of every future session."
+
+Do not ask more than two questions. Do not add extra fields. Do not reformat the user's insight text beyond basic cleanup.

package/.phase2s/skills/retro/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: retro
+description: Weekly engineering retrospective — what shipped, velocity stats, patterns, one improvement to focus on next week
+triggers:
+  - retro
+  - weekly retro
+  - what did we ship
+  - engineering retrospective
+  - what did I ship this week
+  - week in review
+---
+
+Run a structured engineering retrospective for the last 7 days.
+
+Start by gathering data:
+
+```bash
+git log --oneline --since="7 days ago" --format="%h %ad %s" --date=short
+git log --since="7 days ago" --numstat --format="" | awk '{adds+=$1; dels+=$2} END {print adds" additions, "dels" deletions"}'
+git log --since="7 days ago" --format="%s" | grep -iE "^fix|^bug" | wc -l
+git log --since="7 days ago" --format="%s" | grep -iE "^test|^spec" | wc -l
+git log --since="7 days ago" --format="%s" | wc -l
+```
+
+Then analyze and report in this format:
+
+## Retro — [date range]
+
+### What Shipped
+List each meaningful change with a one-sentence explanation of why it matters. Group by theme (features, fixes, tests, infrastructure). Skip noise commits (merge commits, typo fixes, version bumps).
+
+### Velocity
+- Commits: N
+- Lines changed: +adds / -dels
+- Fix ratio: N% (commits starting with fix/bug)
+- Test ratio: N% (commits touching test files)
+
+### Patterns
+What do the commit messages tell you about where time was actually spent? Any repeated fixes in the same area (churn)? Any days with no commits (blockers or context switching)?
+
+### One Thing to Improve
+Pick the single most actionable improvement for next week based on the patterns. Concrete and specific — not "write more tests" but "add tests for the sandbox edge cases flagged in TODOS.md."
+
+Save the report to `.phase2s/retro/[YYYY-MM-DD].md` after generating it.

package/.phase2s/skills/review/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: review
+description: Code review — read the current diff and give structured, actionable feedback
+triggers:
+  - review my code
+  - code review
+  - check my diff
+  - review this
+---
+
+You are doing a thorough code review. Follow these steps exactly:
+
+1. Run `git diff HEAD` to see all uncommitted changes. If the diff is empty, run `git diff HEAD~1` to see the last commit.
+2. Read any files that are relevant to understanding the changes (imports, interfaces, callers).
+3. Deliver a structured review in this format:
+
+---
+
+## Code Review
+
+**Files changed:** [list them]
+
+### What's good
+[2-4 specific things done well — be concrete, name the function/line]
+
+### Issues
+
+For each issue, format as:
+**[SEVERITY: critical | warn | nit]** `filename:line` — [what's wrong and why it matters]
+[Suggested fix, shown as a code snippet if helpful]
+
+Severity guide:
+- critical = bug, data loss, security hole, will fail in production
+- warn = wrong behavior in an edge case, missing error handling, performance problem
+- nit = style, naming, readability — fine to skip
+
+### Summary
+[1-2 sentences: overall quality and the one thing that most needs attention]
+
+---
+
+Be specific. Name the file and line number. Show actual code in suggestions. If something is genuinely well-designed, say so plainly. If something is a mess, say that too.

package/.phase2s/skills/satori/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: satori
+description: Persistent execution — run a task, verify with tests, retry until passing
+retries: 3
+model: smart
+triggers:
+  - satori
+  - keep going until done
+  - don't stop until it works
+  - iterate to completion
+  - loop until passing
+  - run until tests pass
+---
+
+You are running in satori mode — persistent execution until verified complete.
+
+## Your mandate
+
+Implement the task fully. Do not stop after writing code. After each implementation pass:
+1. State what you implemented and why
+2. Identify what you expect to fail in the verify step and why
+3. Wait for the verification result
+
+If verification fails, you will receive the test output. Analyze it carefully:
+- Which tests failed?
+- What is the root cause (not just the symptom)?
+- What specific change will fix it?
+
+Implement the fix. Be surgical — change only what the failure requires.
+
+## State tracking
+
+A context snapshot was written before this run started at `.phase2s/context/`. Read it to recover state if needed.
+
+After each attempt, a log is written to `.phase2s/satori/` with attempt number, pass/fail, and failure lines.
+
+## Completion
+
+When verification passes, summarize:
+- What was built
+- How many attempts it took and why earlier attempts failed
+- Anything unexpected you discovered
+
+You succeed when the tests are green. Not before.

package/.phase2s/skills/scope-review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: scope-review
+description: Scope and ambition review — challenges whether the plan is doing the right thing at the right scale
+triggers:
+  - think bigger
+  - expand scope
+  - strategy review
+  - challenge the scope
+  - is this ambitious enough
+  - scope review
+  - rethink this
+  - is this the right approach
+  - challenge my plan
+---
+
+Run a scope and ambition review on the current plan or design. This is not an implementation review (that's `/plan-review`) — this challenges whether we're solving the right problem at the right scale.
+
+**First, ask what mode to use:**
+
+Ask the user (AskUserQuestion if available, otherwise as plain text):
+
+> Which mode?
+> A) **Expand** — what's the 10x version of this? What are we leaving on the table?
+> B) **Hold** — maximum rigor on the stated scope. Find what we're missing within it.
+> C) **Reduce** — strip to absolute essentials. What can we cut?
+> D) **Challenge** — adversarial mode. What's wrong with the fundamental approach?
+
+Then read the plan file if provided, or gather context:
+```bash
+cat TODOS.md 2>/dev/null | head -60
+git log --oneline -10
+```
+
+---
+
+## Review Sections
+
+### 1. Problem Definition
+Is the problem being solved actually the right problem? Could a different framing unlock a better solution? What would have to be true for this to be wrong?
+
+### 2. Scope Boundary
+What's in scope? What's explicitly out of scope? What's ambiguously in between and likely to cause pain later? Name 3 things that will probably be "just one more thing" mid-implementation.
+
+### 3. Long-term Trajectory
+Does this decision close future doors or keep them open? What would a v2 look like? Does the v1 architecture support it?
+
+### 4. What's Being Deferred
+List everything in TODOS.md or marked "future" or "deferred." For each: is this actually deferrable or is it a hidden dependency on the current work?
+
+### 5. The 10x Version (Expand mode only)
+What would this look like if done at full ambition? What would it take to get there? Is there a smaller version of the 10x idea that could be included without blowing up scope?
+
+### 6. The MVP (Reduce mode only)
+What is the absolute minimum that delivers real value? What can be cut without losing the core value proposition? What's being built out of habit or convention rather than necessity?
+
+### 7. The Adversarial Challenge (Challenge mode)
+What's the most fundamental objection to this approach? What would a skeptic say? What would they be right about?
+
+---
+
+End with a verdict:
+- **SCOPE IS RIGHT** — proceed
+- **CONSIDER EXPANDING** — specific additions worth the cost
+- **CONSIDER REDUCING** — specific cuts worth making
+- **RETHINK FUNDAMENTALS** — something more significant needs to change