agentleFS
mysleekdesignsmysleekdesigns/crawlforge-mcp/.claude/skills/next-phase/SKILL.md

next-phase

Skill6 starsChanged 35 days agoMITView on GitHub

Drive the next incomplete phase of the remediation plan in the plan/ folder to completion. Auto-detects the next phase (Phase 0 → Phase 6), spawns specialized sub-agents IN PARALLEL to do the work, runs that phase's verification gate plus npm run test:unit and npm test, updates the phase file / plan README / PRD.md / docs/CHANGELOG.md / docs/PRODUCTION_READINESS.md, then commits and pushes to the current branch. One phase per invocation.

  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 12 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never amend: Always create a new commit.

    line 32
  2. Distinctive:

    If the working tree is dirty before Step 1 (anything other than the plan files themselves), stop and report — don't sweep other work into …

    line 35
  3. Distinctive:

    If any verification step fails, stop before commit, leave the tree as-is, and report the failure with output.

    line 36
  4. Very specific:

    All sub-agent calls in Step 3 go out in a single message with multiple Agent tool calls so they run in parallel.

    line 37
  5. Very specific:

    Disjoint file ownership: No two parallel agents may edit the same file (they share the real working tree, not worktrees — concurrent edits …

    line 38
  6. Very specific:

    If every - [ ] in every phase file is already - [x], output All phases complete — nothing to do.

    line 45
  7. Distinctive:

    Read the current phase file in full.

    line 46
  8. Very specific:

    Every unchecked - [ ] item in ## Checklist, verbatim, plus each item's file:line and Fix: sub-bullets.

    line 49
  9. Very specific:

    Run git status --short and git rev-parse --abbrev-ref HEAD.

    line 51
  10. Distinctive:

    If the current phase is a DECISION phase, do not start work.

    line 55
  11. Very specific:

    Use AskUserQuestion to get the call.

    line 58
  12. Very specific:

    Phase 2 is large (~52 items): Do NOT hand it to one agent.

    line 76
  13. Distinctive:

    After all agents return:

    line 106
  14. Distinctive:

    Run git status --short and git diff --stat.

    line 108
  15. Very specific:

    Run this phase's ## Verification gate (the checklist from the phase file — its live re-smokes and assertions) plus the project-standard …

    line 110
  16. Distinctive:

    If anything fails: stop. Do not edit the plan.

    line 116
  17. Distinctive:

    Only on full verification success:

    line 120
  18. Very specific:

    Commit with a HEREDOC. Title: Phase <N> — <phase title>.

    line 132
  19. Distinctive:

    Not a code generator — all implementation is delegated.

    line 158
  20. Very specific:

    Not a phase planner — phases are already defined in plan/.

    line 159
  21. Distinctive:

    Not a multi-phase runner — it ships exactly one phase, then stops.

    line 160
  22. Distinctive:

    Not idempotent on partial failure — if Step 4 fails, the tree is left dirty for you to inspect.

    line 161

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/next-phase — Ship the next phase of the plan/ folder

You orchestrate exactly one phase of the remediation plan in plan/ from start to push, then stop. Repeated invocations walk the plan in order: Phase 0 → 1 → 2 → 3 → 4 → 5 → 6. You do not implement the work yourself — you delegate to specialized sub-agents in parallel and integrate their work.

The plan lives in plan/:

  • plan/README.md — index + sequencing + the phase table.
  • plan/phase-0-dependency-currency.md … plan/phase-6-mcp-competitive.md — one file per phase.
  • Full failure detail for every finding: docs/CODEBASE_AUDIT_2026-08.md.

Each phase file has a ## Checklist of - [ ] items and a ## Verification gate of - [ ] items. A code finding looks like:

- [ ] 🔴 **<title>** · CONFIRMED
  - `src/utils/ssrfGuard.js:129`
  - Failure: <concrete failure scenario>
  - Fix: <the fix>

The `file:line` and Fix: sub-bullets are the contract you hand to the sub-agent — copy them verbatim, don't paraphrase.

Hard rules

  • One phase per invocation. Detect the lowest-numbered incomplete phase, ship it, stop.
  • Never amend. Always create a new commit.
  • Never --no-verify, --no-gpg-sign, or force-push.
  • Never git add -A / git add . — stage files by name.
  • If the working tree is dirty before Step 1 (anything other than the plan files themselves), stop and report — don't sweep other work into the commit.
  • If any verification step fails, stop before commit, leave the tree as-is, and report the failure with output.
  • All sub-agent calls in Step 3 go out in a single message with multiple Agent tool calls so they run in parallel.
  • Disjoint file ownership. No two parallel agents may edit the same file (they share the real working tree, not worktrees — concurrent edits to one file corrupt it). server.js and shared src/utils/* are hotspots; give each hot file to a single agent.
  • In this environment, git, npm install/update, and the test suites may fail under a restrictive sandbox (listen EPERM / write EPERM are artifacts, not real failures). If a step fails that way, re-run it with the sandbox disabled. Manual node --test runs need --test-force-exit placed before the file path (after it, the flag is silently ignored; a Playwright handle otherwise hangs the exit — see CLAUDE.md). npm run test:unit already sets it.

Step 1 — Detect the next phase

  1. List plan/phase-*.md and order them by phase number (0 → 6).
  2. The current phase is the first file (lowest number) containing at least one - [ ] line.
  3. If every - [ ] in every phase file is already - [x], output All phases complete — nothing to do. and exit.
  4. Read the current phase file in full. Record:
    • Phase number + title (from the # Phase N — … heading).
    • Whether it is a DECISION phase (its goal contains **DECISION** or the README table marks it "Yes" under "Needs a decision?"). Phases 5 and 6 are DECISION phases.
    • Every unchecked - [ ] item in ## Checklist, verbatim, plus each item's file:line and Fix: sub-bullets.
    • The ## Verification gate block verbatim.
  5. Run git status --short and git rev-parse --abbrev-ref HEAD. If the tree is dirty (anything other than files under plan/), stop and report.

DECISION-phase gate (Phases 5 & 6)

If the current phase is a DECISION phase, do not start work. Instead:

  • Surface the decision(s) the phase names (e.g. Phase 5: "raise engines.node to >=20?"; Phase 6: which spec-adoption / competitive items to pursue).
  • Use AskUserQuestion to get the call. Only the items the user greenlights become in-scope; leave the rest - [ ].
  • Then proceed with Steps 2–5 for the greenlit subset only. Never auto-implement a roadmap/competitive item (Phase 6 Track B/C) the user did not choose.

Step 2 — Plan parallel delegation

Group the in-scope unchecked items by owning agent, primarily from each finding's file:line. Mapping:

Finding area (by file / theme)Sub-agent
SSRF (src/utils/ssrfGuard.js, ssrfProtection.js), OAuth (src/server/auth/oauth.js), auth/billing (src/core/AuthManager.js, src/server/withAuth.js), secret masking, webhook SSRFsecurity-auditor
Tool logic & core in src/tools/** and src/core/** (crawlers, cache, processing, analysis, Snapshot/ChangeTracker, Research, Localization, Stealth), server.js handlers/schemasmcp-implementation
Real-module unit/integration tests, SSRF regression suite, coverage, npm test, node test-tools.js, npm audittesting-validation
Leak assertions (WeakRef/--expose-gc), soak/RSS/memory, browser-pool loadperformance-monitor
docs/**, PRD.md, docs/CHANGELOG.md, README.md, docs/PRODUCTION_READINESS.mdapi-documenter
npm update, dependency bumps/removals in package.json, Node-floor bump, Docker/npm verification, version bumpdeployment-manager

Notes:

  • Phase 0 and Phase 5 are dependency/ops phases (no severity-emoji findings) — lead with deployment-manager, verify with testing-validation.
  • Phase 2 is large (~52 items). Do NOT hand it to one agent. Shard the mcp-implementation work into several parallel agents by disjoint subsystem/file set (e.g. basic+scrape, crawl+map, extract+document, search+research, batch+actions) so no two agents share a file. Assign all server.js findings to a single agent.
  • Do NOT delegate the final commit + push or the plan checkbox flips. You do those in Step 5.
  • Within one agent's group, items are sequential; across groups, parallel.

Step 3 — Execute agents in parallel

Send one message containing one Agent tool call per group. Each prompt must:

  1. State the phase number + title + a one-line goal.
  2. Include the agent's owned items verbatim, each with its `file:line` and Fix: line.
  3. List the exact files the agent owns (disjoint from every other agent this round).
  4. Forbid: touching files outside its list, editing anything under plan/, committing, or pushing.
  5. End with: "Report the exact files you modified and a one-line result per item — only what you actually did, not what you would do."

Prompt skeleton (fill in real items — do not copy literally):

You are shipping part of Phase <N> — <title> of the plan/ folder. Goal: <one line>.
Your owned items (verbatim from plan/phase-<N>-*.md):
- [ ] <emoji> <title>
    file:line: <src/...:NN>
    fix: <the fix text>

Owned files (touch ONLY these): <disjoint file list>
Forbidden: editing anything under plan/, committing, pushing, touching files outside the list.
When done, report: (1) files modified, (2) one-line outcome per item.

Step 4 — Integrate and verify

After all agents return:

  1. Run git status --short and git diff --stat.
  2. For each owned item, confirm the change is actually in the diff. Trust the code, not the agent's summary. If an item wasn't done, re-delegate it or do it yourself. Reconcile any two agents that touched the same file (should not happen with disjoint ownership — if it did, re-read and merge both intents by hand).
  3. Run this phase's ## Verification gate (the checklist from the phase file — its live re-smokes and assertions) plus the project-standard suites:
    npm run test:unit          # expect every test to pass
    npm test                   # expect 100.0% COMPLIANT, 0 errors
    For dependency phases (0, 5) also run npm audit and confirm the targeted advisories cleared. Run any phase-specific commands the gate names (e.g. node test-tools.js, a soak test).
  4. If anything fails: stop. Do not edit the plan. Do not commit. Report which gate item failed and the output.

Step 5 — Update plan, commit, push

Only on full verification success:

  1. Edit the phase file: flip every completed - [ ] → - [x] (checklist items and verification-gate items). Under the # Phase N heading, append: **Completed:** YYYY-MM-DD (today's real date). For a partial DECISION phase, flip only the greenlit items and note which were deferred.
  2. Edit plan/README.md: in the phase table, mark the phase done (e.g. append ✅ to its row) so the index reflects progress.
  3. Edit PRD.md: append the version/phase entry per the standing rule in the feedback_commit_update_prd memory. Match the format of prior entries.
  4. Edit docs/CHANGELOG.md: append a section summarizing what shipped. Match prior entries.
  5. Edit docs/PRODUCTION_READINESS.md: record the phase completion (project rule: sub-agents report, PM updates this file).
  6. Stage named files only — every file the agents touched plus the plan/PRD/CHANGELOG/docs edits:
    git add plan/phase-<N>-*.md plan/README.md PRD.md docs/CHANGELOG.md docs/PRODUCTION_READINESS.md <other modified files>
    Never git add -A.
  7. Commit with a HEREDOC. Title: Phase <N> — <phase title>. Body: short bullets of what shipped (grouped by theme/subsystem). End the body with the Co-Authored-By trailer your environment's git rules specify (e.g. Co-Authored-By: Claude <noreply@anthropic.com>).
    git commit -m "$(cat <<'EOF'
    Phase 1 — Critical Security Holes (SSRF · OAuth · Secrets · Billing)
    
    - Unified SSRF pre-flight across every outbound fetch path (fetch/scrape/map/pdf/actions/webhook)
    - Fixed IP-literal + IPv4-mapped-IPv6 guard bypass
    - Closed anonymous OAuth token mint; masked secrets in usage telemetry
    - No credits billed when the credit check itself refuses the call
    - Added SSRF regression suite
    
    Co-Authored-By: Claude <noreply@anthropic.com>
    EOF
    )"
  8. git push to the current branch. Never push to main; never force. (gh/git may need the sandbox disabled here — see the gh-cli-needs-sandbox-off / running-tests-sandbox memories.)
  9. Final report: phase number, commit SHA, branch, what shipped (one line per theme), the npm run test:unit / npm test results, and which phase runs next on the next /next-phase invocation.

When agents conflict or stall

  • Two agents touched the same file → your ownership wasn't disjoint; re-read the file, reconcile by hand, keep both intents, and tighten ownership next round.
  • An agent reports it couldn't do an item → re-prompt with sharper constraints, or downgrade scope and leave the item - [ ]. Never mark - [x] something that wasn't done.
  • A verification step is flaky → re-run once. If it fails twice, treat it as real and stop.

What this skill is NOT

  • Not a code generator — all implementation is delegated.
  • Not a phase planner — phases are already defined in plan/.
  • Not a multi-phase runner — it ships exactly one phase, then stops. Invoke again for the next.
  • Not idempotent on partial failure — if Step 4 fails, the tree is left dirty for you to inspect.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.