skillshop 2.0.0 → 2.2.0

package/skills-content/flare/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: flare
+description: Runs the current app's local web server and exposes it with a Cloudflare Quick Tunnel using the `cloudflared` CLI. Use when the user invokes `/flare`, says "flare it", "flare this app", "tunnel it", or asks for a temporary public URL to the local app.
+metadata:
+  author: Daniel Fosco
+  version: "2026.8.31"
+---
+
+# Flare
+
+> Triggered by: `/flare`, "flare it", "flare this", "flare the app", "tunnel it", "give me a public URL"
+
+Start or reuse the current application's local web server, then expose it through a temporary `trycloudflare.com` URL with `cloudflared`.
+
+## 1. Identify the app server
+
+Inspect repository guidance, package scripts, lockfiles, workspace configuration, and framework configuration before running anything. Use the app and command implied by the user's current directory and request.
+
+- Prefer a documented development command such as `npm run dev`, `pnpm dev`, `yarn dev`, or the repository's equivalent.
+- In a monorepo, run the command from the relevant app directory or use its documented workspace filter. Do not expose an arbitrary sibling app.
+- Reuse an already-running server only when its process, port, and response clearly belong to the requested app.
+- Do not install dependencies, choose between several plausible apps, or invent a server command without asking one short question.
+- Bind only to loopback when the framework supports it. A Cloudflare tunnel does not require the server to listen on `0.0.0.0`.
+
+Determine the local URL from configuration or startup output. Do not assume a framework's default port if the app selected another available port.
+
+## 2. Check prerequisites and exposure risk
+
+Verify that `cloudflared` is available:
+
+```sh
+cloudflared --version
+```
+
+If it is missing, report that clearly and ask before installing system software. Use the platform's official Cloudflare package or installation instructions; do not substitute an unrelated npm wrapper.
+
+The user's flare request authorizes creating a temporary public tunnel, but not exposing obviously sensitive data. Before tunneling, stop for confirmation if the app is an admin surface, bypasses authentication in development, contains customer data, or grants destructive capabilities. Never print or place secrets in the public URL, command arguments, or logs.
+
+## 3. Start and verify the server
+
+If no suitable server is already running, create a temporary run directory and start the repository-native command as a detached process. Keep logs and the process ID so the user can diagnose and stop it later.
+
+Example shape, adapted to the actual command rather than copied blindly:
+
+```sh
+run_dir="$(mktemp -d "${TMPDIR:-/tmp}/flare.XXXXXX")"
+nohup npm run dev >"$run_dir/server.log" 2>&1 &
+printf '%s\n' "$!" >"$run_dir/server.pid"
+```
+
+Read the startup log until the actual local URL is known. Verify that URL with `curl` or an equivalent HTTP request before starting the tunnel. A redirect or expected authentication response can be healthy; connection failures and server errors are not. If startup fails, inspect the server log, fix only issues within the user's requested scope, and do not launch a tunnel to a dead port.
+
+When reusing an existing server, still create a run directory for the tunnel metadata, but do not claim ownership of or stop that server during cleanup.
+
+## 4. Start the Quick Tunnel
+
+Start `cloudflared` detached against the verified loopback URL:
+
+```sh
+nohup cloudflared tunnel --no-autoupdate --url "http://127.0.0.1:PORT" >"$run_dir/cloudflared.log" 2>&1 &
+printf '%s\n' "$!" >"$run_dir/cloudflared.pid"
+```
+
+Use the app's actual scheme, host, and port in place of the example. This is a Quick Tunnel; do not create DNS records, log into a Cloudflare account, or configure a named tunnel unless the user explicitly asks for a persistent tunnel.
+
+Quick Tunnels are incompatible with a default `config.yaml` in the user's `.cloudflared` directory. If one exists, leave it untouched, create an empty YAML file inside `run_dir`, and pass it explicitly with `--config "$run_dir/quick-tunnel.yml"`. Verify `--config` support in `cloudflared tunnel --help` before doing so. Never rename, edit, or replace the user's named-tunnel configuration.
+
+Watch `cloudflared.log` for the generated `https://*.trycloudflare.com` URL and for early process failure. Allow startup time, but use a bounded wait rather than leaving a foreground command blocked indefinitely.
+
+Request the public URL once to verify that it reaches the app. If verification fails, inspect both logs and stop processes started by this run rather than reporting a broken URL.
+
+## 5. Report and manage lifecycle
+
+On success, report:
+
+- the public `https://*.trycloudflare.com` URL;
+- the local app URL and server command;
+- whether the server was started or reused;
+- the temporary run directory containing logs and PID files;
+- that the URL is for development only, has no uptime guarantee, does not support Server-Sent Events, and remains available only while `cloudflared` is running;
+- an exact cleanup command for processes this run started.
+
+Use graceful process termination for cleanup. For a server started by this run, the cleanup shape is:
+
+```sh
+kill "$(cat "$run_dir/cloudflared.pid")" "$(cat "$run_dir/server.pid")"
+```
+
+If the server was reused, omit its PID and stop only `cloudflared`. Do not use broad commands such as `pkill cloudflared`, because they can terminate unrelated tunnels. Do not delete the run directory until its processes have stopped; retain failed-run logs long enough to report the cause.
+
+## Failure rules
+
+- Do not report a public URL unless both the local and tunneled HTTP checks succeed.
+- If either detached process exits early, report the relevant log output and clean up the other process if this run started it.
+- Never silently switch to a production server, deploy the app, expose a different port, or weaken application authentication to make the tunnel work.
+- Treat the random hostname as public. Quick Tunnels provide transport, not application authorization.

package/skills-content/grilling/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+metadata:
+  author: Matt Pocock
+  version: "2026.10.02"
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/skills-content/install-sigmap/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: install-sigmap
+description: Installs and configures SigMap for a repository, including OpenCode MCP wiring, local indexing, generated context, Git ignores, and quiet-by-default agent guidance. Use when setting up SigMap, repository grounding, or SigMap context.
+metadata:
+  author: Daniel Fosco
+  version: "2026.9.8"
+---
+
+# Install SigMap
+
+Set up SigMap in the current Git repository. SigMap is a local indexing and
+grounding tool; it must not become unsolicited conversation content.
+
+## Procedure
+
+Run these commands from the repository root:
+
+```bash
+npm install --global sigmap
+sigmap mcp install opencode --global
+sigmap
+```
+
+The OpenCode installer may write a legacy `~/.config/opencode/config.json`
+entry. OpenCode 1.18+ reads `~/.config/opencode/opencode.json`; ensure that
+file preserves its existing fields and contains this valid MCP entry:
+
+```json
+{
+  "mcp": {
+    "sigmap": {
+      "type": "local",
+      "command": ["/absolute/path/to/sigmap", "--mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Use the resolved `sigmap` executable path rather than an ephemeral `npx`
+cache path. Preserve any existing MCP servers and provider settings.
+
+## Repository files
+
+SigMap's local index belongs in `.context/` and its generated context must not
+be committed. Add these root-anchored entries to `.gitignore`, preserving
+existing rules and avoiding duplicates:
+
+```gitignore
+# SigMap — local index, generated context, and configuration.
+/.context/
+/.contextignore
+/.repomixignore
+/gen-context.config.json
+/.github/copilot-instructions.md
+/.github/openai-context.md
+/.github/gemini-context.md
+/.github/context-*.md
+```
+
+If a generated context file is already tracked, remove it from the index with
+`git rm --cached` while keeping the local file. Do not remove source files or
+hand-authored instructions.
+
+## Quiet-by-default instruction
+
+Ensure `.github/copilot-instructions.md` contains this instruction before the
+generated SigMap section. Add it only once, and preserve it across future
+regeneration:
+
+```md
+## SigMap usage
+
+Do not mention SigMap, its index, context, MCP tools, or SigMap workflow in
+normal daily responses. Use it silently when useful. Only output SigMap
+details when the user actively runs a `sigmap` command or directly refers to
+SigMap.
+```
+
+If the file is regenerated, reinsert the instruction before the
+`## Auto-generated signatures` marker if needed. This instruction applies to
+agent output, not to command output when a user explicitly runs SigMap.
+
+## Validation
+
+Run:
+
+```bash
+sigmap --version
+opencode mcp list
+sigmap doctor --json
+git check-ignore -v .context/sig-index.json .github/copilot-instructions.md
+```
+
+The MCP server must report `connected`. `sigmap doctor` may warn about index
+coverage or freshness; report those warnings rather than claiming a clean
+index. Tell the user to restart OpenCode after changing its configuration.

package/skills-content/one-shot/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: one-shot
+description: Fast, single-pass implementation mode. Use when the user says "one-shot", "one shot, go", "prioritize speed", or asks to skip planning, delegation, and broad testing in favor of immediate development.
+metadata:
+  author: Daniel Fosco
+  version: "2026.8.21"
+---
+
+# One Shot
+
+> Triggered by: "one-shot", "one shot, go", "prioritize speed over correctness", "development over testing", "no sub-agents"
+
+Execute the requested change immediately in one focused pass. Optimize for delivery speed and working implementation rather than exhaustive investigation, review, or test coverage.
+
+## Operating mode
+
+1. **Act immediately.** Do not present a plan, create tracking artifacts, or ask for confirmation when a reasonable implementation choice exists.
+2. **Work directly.** Do not launch sub-agents, factories, or delegated reviews. Use direct repository and editing tools only.
+3. **Explore narrowly.** Read only the files and nearby conventions needed to make the change safely. Avoid broad architecture surveys and speculative searches.
+4. **Implement once.** Make one coherent, surgical edit that addresses the full request. Do not add unrelated refactors, abstractions, documentation, or tests.
+5. **Validate minimally.** Prefer the fastest targeted check that can catch syntax, type, build, or behavior regressions in the changed surface. Do not run broad test suites unless the change is high-risk or the targeted check fails.
+6. **Finish concisely.** Report the outcome and any material limitation. Do not add a retrospective, optional follow-ups, or an offer to continue.
+
+## Priority order
+
+When tradeoffs are necessary, use this order:
+
+1. User intent and safety constraints
+2. A working end-to-end implementation
+3. Speed and minimal scope
+4. Existing codebase conventions
+5. Targeted validation
+6. Additional tests, polish, and documentation
+
+## Guardrails
+
+- "One shot" removes ceremony, not responsibility. Never bypass security, privacy, or destructive-action safeguards.
+- Do not knowingly ship broken code. If the direct approach fails, fix the failure rather than stopping at a partial result.
+- Do not silently guess when ambiguity could cause irreversible harm or substantial wasted work; ask only in that case.
+- Preserve unrelated user changes in a dirty worktree.
+- Do not claim success unless the requested outcome is present and the minimal relevant check passes.
+
+## Default interpretation
+
+Treat this request:
+
+> Prioritize speed over correctness, development over testing. No sub-agents. One shot, GO.
+
+as:
+
+> Implement now, directly and in one focused pass. Favor a complete practical change over exhaustive analysis and test coverage. Use no delegation, avoid ceremony and unrelated work, run only the smallest meaningful validation, and preserve mandatory safety and repository constraints.

package/skills-content/release/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: release
+description: Creates a versioned release using the current repository's native versioning, tagging, validation, and publishing workflow.
+metadata:
+  author: Daniel Fosco
+  version: "2026.8.30"
+---
+
+# Release Skill
+
+> Triggered by: "release", "cut a release", "publish a release", "release a new version", "ship a release", "do a release"
+>
+> This skill is always invoked manually. Other skills must not trigger a release automatically.
+
+## What This Does
+
+Orchestrates a release from repository evidence. It does not assume npm, Changesets, fixed package versions, a tag prefix, a workflow filename, or a publishing provider.
+
+## How to Execute
+
+### 1. Establish the release contract
+
+Read repository instructions and release-related files before changing anything:
+
+- `AGENTS.md`, `CONTRIBUTING.md`, release documentation, and package manifests;
+- versioning configuration such as `.changeset/config.json`, release-please, semantic-release, Cargo, Go, Python, or other ecosystem files;
+- package-manager lockfiles and release scripts;
+- CI workflows that publish artifacts or create hosted releases;
+- existing changelogs and recent release commits.
+
+Inspect current state:
+
+```bash
+git status --short
+git branch --show-current
+git remote -v
+git tag --list --sort=-version:refname
+```
+
+Do not release from a dirty tree unless the documented workflow intentionally consumes those exact changes and the user confirms them. Do not assume releases happen from `main` or from a feature branch; enforce the repository's policy.
+
+### 2. Determine scope and previous release
+
+Identify the package or release unit, its tag family, and the latest reachable release tag. In a monorepo, determine whether packages are independently versioned, linked, or fixed from configuration rather than package counts or naming.
+
+Use the relevant tag as the start of the release range and verify it:
+
+```bash
+git rev-parse --verify '<last-tag>^{commit}'
+git --no-pager log '<last-tag>'..HEAD --oneline --no-merges
+```
+
+Handle a first release explicitly when no prior tag exists.
+
+### 3. Propose the release
+
+Derive a suggested semantic bump from actual compatibility impact:
+
+- `major`: breaking public behavior or API;
+- `minor`: backward-compatible user-facing functionality;
+- `patch`: backward-compatible fixes;
+- use the repository's scheme when it is not semantic versioning.
+
+Ask the user to confirm the release unit, target version or bump, channel, and generated summary. Show excluded commits and any ambiguity. Do not treat conventional-commit prefixes as proof of compatibility.
+
+### 4. Run the native versioning workflow
+
+Prefer documented repository scripts. If the repository uses Changesets:
+
+1. Create a changeset listing every affected package required by `.changeset/config.json`.
+2. Enter prerelease mode only for a requested prerelease channel.
+3. Run the repository's version command, or the package-manager equivalent of `changeset version` when no wrapper exists.
+4. Read generated manifests and changelogs to obtain the resulting versions.
+
+For other release systems, use their checked-in configuration and documented commands. Never substitute a familiar tool merely because the repository lacks one.
+
+### 5. Review and validate
+
+Inspect the complete release diff. Confirm that versions, lockfiles, changelogs, generated artifacts, and package relationships changed as intended. Run the repository's required release checks, tests, and builds.
+
+Stop on unexpected package bumps, missing changelog entries, test failures, or generated files unrelated to the release. Do not discard pre-existing changes.
+
+### 6. Confirm irreversible actions
+
+Before committing, tagging, pushing, publishing, or dispatching CI, show the exact planned commands and ask for confirmation unless the user's request already explicitly authorized those actions.
+
+Use the repository's release commit convention. Create tags with its established command or tag format. Verify every tag points at the intended commit before pushing.
+
+Push a branch and tags separately when CI depends on tag events. Trigger a workflow manually only when repository documentation requires it; discover the workflow name and inputs rather than guessing them.
+
+### 7. Verify publication
+
+Verify each expected artifact through the relevant registry, CI system, and hosted release provider. Compare the published version and release notes with the local release commit. Report pending CI as pending, not successful.
+
+If generated changelog text contains inappropriate boilerplate or contributor attribution, preserve the repository's policy and correct the source configuration where practical rather than hard-coding an author's identity.
+
+### 8. Report
+
+Report:
+
+- release unit and version;
+- release commit and tags;
+- validations run and their outcomes;
+- pushed refs and triggered workflows;
+- publication URLs or pending jobs;
+- any manual follow-up.
+
+## Failure Recovery
+
+Inspect state before retrying. A failed release may already have a version commit, local tag, remote tag, registry artifact, or running workflow. Resume with repository-provided recovery scripts when available. Never recreate, move, or delete a published tag without explicit user approval and a documented recovery plan.
+
+## Rules
+
+1. Never invoke this skill without an explicit release request.
+2. Never infer package scope, fixed versioning, tag format, changelog paths, or CI workflow names from this skill.
+3. Get confirmation for release scope and version before versioning.
+4. Get confirmation before irreversible remote actions unless already explicitly authorized.
+5. Treat generated release notes as artifacts to review, not unquestioned source material.
+6. Never report success until the expected remote artifacts are verified.
+
+## Relationship to Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `changeset` | Handles low-level Changesets operations when that tool is configured. |
+| `changelog` | Produces or curates release notes using repository conventions. |
+| `ship` | Delivers code for review; it must not trigger a release automatically. |
+| `worktree` | Provides isolation when the repository's release policy requires it. |

package/skills-content/shadow-clone/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: shadow-clone
+description: Analyzes a source repository and generates planning documents for re-implementing it in any language or stack. Use when asked to shadow clone, port, or replicate a repo.
+metadata:
+  author: Daniel Fosco
+  version: "2026.8.25"
+---
+
+# Shadow Clone
+
+Shadow Clone analyzes a source repository and generates planning documents that enable a complete (or partial) re-implementation — in any language, on any stack.
+
+## When to Use
+
+Use this skill when asked to "shadow clone", "clone the architecture of", "re-implement", "port", or "replicate" a repository or a specific aspect of one.
+
+## Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| **Source** | Yes | One of: a GitHub URL, a local directory path, or pasted README / documentation content. |
+| **Focus prompt** | No | Natural-language direction on *what* to clone. E.g. "just the UI component library", "only the API layer", "the auth system and data models". When omitted, the entire repo is in scope. |
+| **Target language / stack** | No | If the user specifies a target language or framework, tailor technical plans to that stack. Otherwise keep plans language-agnostic. |
+| **Output folder** | No | Explicit directory where documents should be saved. When omitted, the skill auto-detects (see Output Location below). |
+
+## Outputs
+
+Shadow Clone produces **two kinds** of planning documents:
+
+1. **Conceptual Plan** (`shadow-clone-concept.md`) — one document.
+2. **Technical Plans** (`shadow-clone-tech-*.md`) — one or more documents, one per major module or domain area.
+
+These documents should be detailed enough that a developer (or an AI agent) can re-implement the system without access to the original source code.
+
+### Output Location
+
+Documents are always saved as Markdown files to a subfolder named after the source project (e.g. `my-project/`). The parent folder is determined by the following priority:
+
+1. **User-specified folder** — if the user explicitly requests a location, use it exactly.
+2. **`.github/plans/{project}/`** — if a `.github` directory exists in the current working directory.
+3. **`plans/{project}/`** — if a `plans` or `plan` directory exists in the current working directory.
+4. **`{project}/`** — fallback: create the subfolder at the repository root.
+
+Where `{project}` is the source project's directory or repository name (e.g. `gh-alerts-ui`).
+
+Before writing documents, check which parent folder applies (in order) and create the `{project}` subfolder if it doesn't exist.
+
+---
+
+## Procedure
+
+### Phase 1 — Discovery
+
+Goal: build a mental model of the source repo's scope, structure, and stack.
+
+**If the source is a local directory:**
+
+1. Run the repo scanner to get a structural overview:
+   ```bash
+   node .github/skills/shadow-clone/scan-repo.mjs <directory>
+   ```
+   If the user provided a focus area, use the `--focus` flag:
+   ```bash
+   node .github/skills/shadow-clone/scan-repo.mjs <directory> --focus "src/components/**"
+   ```
+
+2. Run the signature extractor to map the public API surface:
+   ```bash
+   node .github/skills/shadow-clone/extract-signatures.mjs <directory>
+   ```
+   Optionally filter by extension:
+   ```bash
+   node .github/skills/shadow-clone/extract-signatures.mjs <directory> --ext .ts,.tsx
+   ```
+
+3. Read the README and any key manifest files identified by the scanner (package.json, Cargo.toml, go.mod, etc).
+
+**If the source is a GitHub URL:**
+
+1. Use GitHub MCP tools (`get_file_contents`) to fetch the README.
+2. Use `get_file_contents` on the root directory to see the file tree.
+3. Fetch key manifest files to understand dependencies and scripts.
+4. Fetch source files as needed for deeper analysis (prioritize entry points and public API).
+
+**If the source is pasted README / docs:**
+
+1. Parse the provided content directly.
+2. If a URL is discoverable in the content, optionally fetch additional context.
+3. Work with what's available — the plans will note gaps and assumptions.
+
+### Phase 2 — Deep Analysis
+
+Goal: understand architecture, patterns, data flow, and key implementation details.
+
+Using the discovery output:
+
+1. **Identify architecture style** — monolith, microservices, serverless, CLI tool, library, etc.
+2. **Map the module graph** — which modules depend on which, what are the boundaries.
+3. **Identify core patterns** — state management, routing, data access, error handling, auth, pub/sub, etc.
+4. **Catalog data models** — schemas, types, interfaces, database models.
+5. **Map external interfaces** — APIs (REST, GraphQL, gRPC), webhooks, CLI commands, UI routes.
+6. **Note configuration & environment** — env vars, config files, feature flags.
+
+Read source files as needed. Prioritize:
+- Entry points and bootstrapping code
+- Router / controller definitions
+- Data model definitions
+- Core business logic modules
+- Configuration and middleware
+- Key utility / helper modules
+
+If the user specified a focus area, concentrate the analysis there but still note enough surrounding context to understand boundaries and dependencies.
+
+### Phase 3 — Write Conceptual Plan
+
+Determine the output folder (see **Output Location** above) and create `shadow-clone-concept.md` there with the following structure:
+
+```markdown
+# Shadow Clone: Conceptual Plan — {Project Name}
+
+> Source: {url or path}
+> Focus: {focus prompt or "Full repository"}
+> Generated: {date}
+
+## 1. Purpose & Overview
+What this project does, who it's for, what problem it solves.
+
+## 2. Architecture Overview
+High-level architecture style, major subsystems, how they connect.
+Include an ASCII diagram if it helps.
+
+## 3. Core Concepts & Domain Model
+Key domain entities, their relationships, core vocabulary.
+
+## 4. Key Design Decisions
+Important architectural choices and their rationale (inferred from the codebase).
+- Why this state management approach?
+- Why this data access pattern?
+- Why this auth strategy?
+
+## 5. Features & Behavior
+User-facing features and behaviors that must be replicated.
+Organized by area / module.
+
+## 6. External Interfaces
+- API endpoints (with methods, paths, request/response shapes)
+- CLI commands
+- UI routes / pages
+- Webhooks / events
+- Database schema (if discoverable)
+
+## 7. Cross-Cutting Concerns
+Error handling, logging, auth, validation, i18n, accessibility, testing strategy.
+
+## 8. Dependencies & Rationale
+Key dependencies, why they're used, and what they'd map to in another stack.
+
+## 9. Assumptions & Gaps
+Things that couldn't be determined from the source and need clarification.
+```
+
+### Phase 4 — Write Technical Plans
+
+Create one or more `shadow-clone-tech-{area}.md` files in the same output folder. Each covers a specific module, layer, or feature area. The number of technical plans depends on the project's complexity:
+
+- Small project / focused clone → 1 technical plan may suffice
+- Medium project → 2–4 technical plans (e.g., `data-model`, `api`, `ui`, `auth`)
+- Large project → as many as needed to cover the scope
+
+Each technical plan follows this structure:
+
+```markdown
+# Shadow Clone: Technical Plan — {Area Name}
+
+> Part of: {Project Name} shadow clone
+> Focus: {what this plan covers}
+
+## 1. Module Overview
+What this module does, its responsibility boundaries.
+
+## 2. File / Module Structure
+Recommended directory layout and file organization for the re-implementation.
+
+## 3. Interfaces & Contracts
+Detailed type definitions, function signatures, API contracts.
+Use the target language if specified, otherwise use TypeScript-style pseudocode.
+
+## 4. Data Models
+Schemas, types, and their validation rules.
+
+## 5. Core Logic
+Step-by-step description of algorithms, state machines, data transformations.
+Enough detail to implement without guessing.
+
+## 6. Integration Points
+How this module connects to other modules. Expected inputs/outputs at boundaries.
+
+## 7. Configuration
+Environment variables, config values, feature flags this module uses.
+
+## 8. Error Handling
+Expected error cases and how they should be handled.
+
+## 9. Testing Strategy
+What to test, key test cases, edge cases to cover.
+
+## 10. Implementation Order
+Suggested sequence for building this module, starting from the foundation.
+```
+
+### Phase 5 — Summary
+
+After writing all documents, provide a brief summary to the user listing:
+- What documents were created
+- What areas are covered
+- Any notable gaps or assumptions
+- Suggested next steps for implementation
+
+---
+
+## Guidelines
+
+- **Be specific, not vague.** Plans should contain concrete details: actual route paths, actual field names, actual algorithm steps. A developer should be able to implement from the plan without guessing.
+- **Infer rationale.** When you can see *why* a design decision was made, explain it. This helps the re-implementer make equivalent (not necessarily identical) choices in their target stack.
+- **Note alternatives.** When a design choice is stack-specific (e.g., Redux for state management), note what the general pattern is (centralized state store with actions and reducers) so it can be mapped to other ecosystems.
+- **Respect the focus.** If the user asked to clone only the UI layer, don't write detailed technical plans for the backend. Do note the backend interfaces the UI depends on.
+- **Use deterministic tools first.** Run `scan-repo.mjs` and `extract-signatures.mjs` before reading individual files — they give a complete structural picture cheaply.
+- **Keep plans self-contained.** Each technical plan should be readable on its own, with enough context to understand the module without reading other plans (cross-reference where needed).