diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
new file mode 100644
index 0000000..b2412d9
--- /dev/null
+++ b/.agents/plugins/marketplace.json
@@ -0,0 +1,21 @@
+{
+ "name": "propulsion",
+ "interface": {
+ "displayName": "Propulsion",
+ "developerName": "Moon Pixels"
+ },
+ "plugins": [
+ {
+ "name": "propulsion",
+ "source": {
+ "source": "local",
+ "path": "./"
+ },
+ "policy": {
+ "installation": "AVAILABLE",
+ "authentication": "ON_INSTALL"
+ },
+ "category": "Coding"
+ }
+ ]
+}
diff --git a/.agents/skills b/.agents/skills
new file mode 120000
index 0000000..42c5394
--- /dev/null
+++ b/.agents/skills
@@ -0,0 +1 @@
+../skills
\ No newline at end of file
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
new file mode 100644
index 0000000..461331f
--- /dev/null
+++ b/.codex-plugin/plugin.json
@@ -0,0 +1,47 @@
+{
+ "name": "propulsion",
+ "version": "1.0.0",
+ "description": "Propulsion workflow routing and skills for agentic coding.",
+ "author": {
+ "name": "Moon Pixels"
+ },
+ "homepage": "https://github.com/moonpixels/propulsion",
+ "repository": "https://github.com/moonpixels/propulsion",
+ "license": "MIT",
+ "keywords": [
+ "propulsion",
+ "codex",
+ "codex-plugin",
+ "opencode",
+ "opencode-plugin",
+ "agentic-coding",
+ "skills",
+ "workflow",
+ "planning",
+ "tdd",
+ "debugging",
+ "review",
+ "guardrails",
+ "developer-tools"
+ ],
+ "skills": "./skills/",
+ "hooks": "./hooks/hooks.json",
+ "interface": {
+ "displayName": "Propulsion",
+ "shortDescription": "Workflow routing and skills for agentic coding.",
+ "longDescription": "Propulsion adds a compact workflow skill set and high-priority startup routing guidance while preserving Codex tools and permissions.",
+ "developerName": "Moon Pixels",
+ "category": "Coding",
+ "capabilities": ["Interactive", "Read", "Write"],
+ "websiteURL": "https://github.com/moonpixels/propulsion",
+ "defaultPrompt": [
+ "Turn my idea into an implementation-ready plan with Propulsion",
+ "Debug and fix this bug with Propulsion guardrails",
+ "Review these changes with the Propulsion review workflow"
+ ],
+ "brandColor": "#FF4F00",
+ "composerIcon": "./assets/propulsion_icon_square.png",
+ "logo": "./assets/banner.png",
+ "screenshots": []
+ }
+}
diff --git a/.opencode/package.json b/.opencode/package.json
deleted file mode 100644
index a286ab1..0000000
--- a/.opencode/package.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "type": "module",
- "dependencies": {
- "@opencode-ai/plugin": "1.4.10"
- }
-}
diff --git a/.opencode/plugins/propulsion.js b/.opencode/plugins/propulsion.js
deleted file mode 100644
index cd60b64..0000000
--- a/.opencode/plugins/propulsion.js
+++ /dev/null
@@ -1,229 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const dirname = path.dirname(fileURLToPath(import.meta.url));
-const skillsDir = path.resolve(dirname, '../../skills');
-const additionalSkillsDir = path.resolve(dirname, '../../additional/skills');
-const additionalCommandsDir = path.resolve(
- dirname,
- '../../additional/commands',
-);
-const propulsionWorkflowPath = path.join(
- skillsDir,
- 'propulsion-workflow',
- 'SKILL.md',
-);
-
-const parseFrontmatterValue = (value) => {
- const trimmed = value.trim();
-
- if (
- (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
- (trimmed.startsWith("'") && trimmed.endsWith("'"))
- ) {
- return trimmed.slice(1, -1);
- }
-
- if (trimmed === 'true') {
- return true;
- }
-
- if (trimmed === 'false') {
- return false;
- }
-
- return trimmed;
-};
-
-const extractFrontmatter = (raw) => {
- const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-
- if (!match) {
- return { frontmatter: {}, content: raw };
- }
-
- const frontmatter = {};
- const frontmatterBlock = match[1] ?? '';
- const content = match[2] ?? '';
-
- // This intentionally supports the tiny flat frontmatter surface used by bundled
- // commands. It is not a general YAML parser.
- for (const line of frontmatterBlock.split(/\r?\n/)) {
- const entryMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-
- if (!entryMatch) {
- continue;
- }
-
- const key = entryMatch[1];
- const value = entryMatch[2];
-
- if (!key || value === undefined) {
- continue;
- }
-
- const parsedValue = parseFrontmatterValue(value);
-
- switch (key) {
- case 'description':
- if (typeof parsedValue === 'string' && parsedValue) {
- frontmatter.description = parsedValue;
- }
- break;
- case 'agent':
- if (typeof parsedValue === 'string' && parsedValue) {
- frontmatter.agent = parsedValue;
- }
- break;
- case 'model':
- if (typeof parsedValue === 'string' && parsedValue) {
- frontmatter.model = parsedValue;
- }
- break;
- case 'subtask':
- if (typeof parsedValue === 'boolean') {
- frontmatter.subtask = parsedValue;
- }
- break;
- default:
- break;
- }
- }
-
- return { frontmatter, content };
-};
-
-const addSkillsPath = (config, skillsPath) => {
- config.skills = config.skills ?? {};
- config.skills.paths = config.skills.paths ?? [];
-
- if (!config.skills.paths.includes(skillsPath)) {
- config.skills.paths.push(skillsPath);
- }
-};
-
-const loadAdditionalCommands = () => {
- if (!fs.existsSync(additionalCommandsDir)) {
- return {};
- }
-
- const commands = {};
-
- for (const entry of fs.readdirSync(additionalCommandsDir, {
- withFileTypes: true,
- })) {
- if (!entry.isFile() || !entry.name.endsWith('.md')) {
- continue;
- }
-
- const filePath = path.join(additionalCommandsDir, entry.name);
- const raw = fs.readFileSync(filePath, 'utf8');
- const { frontmatter, content } = extractFrontmatter(raw);
-
- if (!content.trim()) {
- continue;
- }
-
- commands[path.basename(entry.name, '.md')] = {
- template: content,
- ...(frontmatter.description
- ? { description: frontmatter.description }
- : {}),
- ...(frontmatter.agent ? { agent: frontmatter.agent } : {}),
- ...(frontmatter.model ? { model: frontmatter.model } : {}),
- ...(typeof frontmatter.subtask === 'boolean'
- ? { subtask: frontmatter.subtask }
- : {}),
- };
- }
-
- return commands;
-};
-
-const mergeAdditionalCommands = (config, additionalCommands) => {
- if (Object.keys(additionalCommands).length === 0) {
- return;
- }
-
- config.command = config.command ?? {};
-
- // Bundled commands are defaults only. A user command with the same name wins.
- for (const [name, definition] of Object.entries(additionalCommands)) {
- if (!(name in config.command)) {
- config.command[name] = definition;
- }
- }
-};
-
-const getBootstrapContent = () => {
- if (!fs.existsSync(propulsionWorkflowPath)) {
- return null;
- }
-
- const raw = fs.readFileSync(propulsionWorkflowPath, 'utf8');
- const { content } = extractFrontmatter(raw);
-
- return `
-**If you were dispatched as a subagent to execute a specific task, IGNORE THIS MESSAGE.**
-
-You are using the Propulsion workflow.
-
-**IMPORTANT: The workflow skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "propulsion-workflow" again - that would be redundant.**
-
-${content}
-`;
-};
-
-export const PropulsionPlugin = async (_pluginInput, options = {}) => {
- const { additional = false } = options;
- const additionalCommands = additional ? loadAdditionalCommands() : {};
-
- return {
- config: async (config) => {
- addSkillsPath(config, skillsDir);
-
- if (additional && fs.existsSync(additionalSkillsDir)) {
- addSkillsPath(config, additionalSkillsDir);
- mergeAdditionalCommands(config, additionalCommands);
- }
- },
-
- 'experimental.chat.messages.transform': async (
- _transformInput,
- output,
- ) => {
- const bootstrap = getBootstrapContent();
-
- if (!bootstrap || output.messages.length === 0) {
- return;
- }
-
- const firstUser = output.messages.find(
- (message) => message.info.role === 'user',
- );
-
- if (!firstUser || firstUser.parts.length === 0) {
- return;
- }
-
- if (
- firstUser.parts.some(
- (part) =>
- part.type === 'text' &&
- part.text.includes('EXTREMELY_IMPORTANT'),
- )
- ) {
- return;
- }
-
- const ref = firstUser.parts[0];
-
- if (!ref || ref.type !== 'text') {
- return;
- }
-
- firstUser.parts.unshift({ ...ref, text: bootstrap });
- },
- };
-};
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index 6204260..398f676 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -2,19 +2,17 @@
"$schema": "./node_modules/oxfmt/configuration_schema.json",
"ignorePatterns": ["node_modules/**", ".opencode/node_modules/**"],
"printWidth": 80,
+ "tabWidth": 4,
"singleQuote": true,
"sortImports": {
"groups": [
- "builtin",
- "external",
- "internal",
- "parent",
- "sibling",
- "index"
+ ["builtin", "external"],
+ ["internal", "subpath"],
+ ["parent", "sibling", "index"],
+ "unknown"
]
},
"sortPackageJson": {
"sortScripts": true
- },
- "tabWidth": 4
+ }
}
diff --git a/AGENTS.md b/AGENTS.md
index 9473976..2b9a46a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,2 +1,2 @@
-- When the user corrects your approach with a reusable, global rule for future work, ask whether they want it added to `AGENTS.md`; if they do, load the `agentic-config` skill and update `AGENTS.md`.
+- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`.
- After implementing changes run `bun run checks` before handoff.
diff --git a/README.md b/README.md
index 971a41c..667f266 100644
--- a/README.md
+++ b/README.md
@@ -2,24 +2,47 @@
# Propulsion
-Propulsion is a compact skill set for agentic coding.
-
-It gives coding agents a stronger workflow: explore unclear work first, write a PRD, turn it into a plan, execute in thin slices with an objective implementation-review loop, and debug from evidence instead of guesses.
+Propulsion is a compact skill set for agentic coding. It gives coding agents a stronger workflow.
## Installation
-Propulsion is installed as an OpenCode plugin.
+### Codex CLI
-Install it for a project by adding it to that project's `opencode.json`:
+Add the Propulsion marketplace:
-```json
-{
- "$schema": "https://opencode.ai/config.json",
- "plugin": ["propulsion@git+https://github.com/moonpixels/propulsion.git"]
-}
+```sh
+codex plugin marketplace add moonpixels/propulsion
+```
+
+Open Codex, run `/plugins`, select the Propulsion marketplace, install
+Propulsion, then restart Codex.
+
+To update:
+
+```sh
+codex plugin marketplace upgrade propulsion
```
-Or install it globally in `~/.config/opencode/opencode.json`:
+### Codex Desktop
+
+Add the Propulsion marketplace with the Codex CLI:
+
+```sh
+codex plugin marketplace add moonpixels/propulsion
+```
+
+Open the desktop app's Plugins page, select the Propulsion marketplace, install
+Propulsion, then restart the app.
+
+To update:
+
+```sh
+codex plugin marketplace upgrade propulsion
+```
+
+### OpenCode
+
+Add Propulsion to `opencode.json`:
```json
{
@@ -28,8 +51,6 @@ Or install it globally in `~/.config/opencode/opencode.json`:
}
```
-Optional extras, including agent-authoring helpers and extra workflow commands, are documented in [`additional/README.md`](additional/README.md).
-
## Acknowledgements
Propulsion is heavily inspired by:
diff --git a/additional/README.md b/additional/README.md
deleted file mode 100644
index b65b7e8..0000000
--- a/additional/README.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Additional OpenCode Assets
-
-These assets are separate from the default Propulsion workflow.
-
-They are optional skills and commands, including agent-authoring helpers and extra workflow commands, and are only included when you explicitly enable them.
-
-## Installation
-
-Add Propulsion to your OpenCode config with the `additional` option enabled:
-
-```json
-{
- "$schema": "https://opencode.ai/config.json",
- "plugin": [
- [
- "propulsion@git+https://github.com/moonpixels/propulsion.git",
- {
- "additional": true
- }
- ]
- ]
-}
-```
diff --git a/additional/commands/commit.md b/additional/commands/commit.md
deleted file mode 100644
index c9a87f8..0000000
--- a/additional/commands/commit.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-description: Automatically stage safe changes and create one local commit
-agent: build
-subtask: true
----
-
-**You are a subagent executing a specific task.**
-
-## Inputs
-
-- Current git status: `git status --short`
-- Current git diff (staged and unstaged): `git diff HEAD`
-- Current branch: `git branch --show-current`
-
-## Instructions
-
-1. Create exactly one commit from current local changes.
-2. Auto-stage relevant changes with `git add -A`, including untracked files.
-3. Unstage excluded files before commit when they are staged.
-4. If there are no committable changes after exclusions, stop and output exactly:
- - `No changes to commit.`
-5. Generate a normal imperative commit subject from the diff, and enforce this format:
- - one line only
- - short descriptive subject line
- - imperative mood
- - normal natural wording
- - no trailing punctuation
-
-## Rules
-
-- NEVER commit likely secret files, ALWAYS unstage them if applicable. Exclude these patterns:
- - `.env`
- - `.env.*`
- - `*.pem`
- - `*.key`
- - `*.p12`
- - `*.pfx`
- - `credentials.json`
- - `*credentials*`
- - `*secret*`
- - `*token*`
- - `.ssh/*`
-- DO NOT push, open PRs, amend, reset, or force anything.
-
-## Output
-
-Use this exact format for your output when the commit succeeds:
-
-- Run `git status --short` before producing the final response.
-
-```md
-Commit created:
-Message:
-Files:
-Excluded secret-like files:
-```
diff --git a/additional/commands/init.md b/additional/commands/init.md
deleted file mode 100644
index 082883e..0000000
--- a/additional/commands/init.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-description: Create or prune AGENTS.md into minimal global steering for this project
-agent: build
-subtask: true
----
-
-**You are a subagent executing a specific task.**
-
-You are initialising OpenCode by creating or pruning AGENTS.md into minimal global steering.
-
-## Instructions
-
-1. Load the `agentic-config` skill immediately and follow it strictly.
diff --git a/additional/commands/pr.md b/additional/commands/pr.md
deleted file mode 100644
index c78939a..0000000
--- a/additional/commands/pr.md
+++ /dev/null
@@ -1,89 +0,0 @@
----
-description: Create or reuse a pull request from the current branch with safe commit + push
-agent: build
-subtask: true
----
-
-**You are a subagent executing a specific task.**
-
-## Inputs
-
-User input: $ARGUMENTS
-
-- If `$ARGUMENTS` is non-empty then treat it as the base branch name
-
-## Instructions
-
-1. Resolve the base branch from `$ARGUMENTS`, or default to the repo's main development branch (e.g. `main`).
-2. Collect context first:
- - `git status --short`
- - `git branch --show-current`
- - `git log --oneline ...HEAD`
- - `git diff ...HEAD`
- - `git diff --stat ...HEAD`
-3. If the current branch matches the chosen base branch, stop and ask the user to confirm the intended base branch.
-4. If the worktree is dirty, invoke `/commit` with no arguments before pushing.
-5. After `/commit`, refresh the branch context before generating PR metadata:
- - `git status --short`
- - `git log --oneline ...HEAD`
- - `git diff ...HEAD`
- - `git diff --stat ...HEAD`
-6. If there is no upstream for the current branch, push with `git push -u origin `. Otherwise, run `git push`.
-7. If push fails because of authentication, permissions, or remote access requires user action, stop and report the failing command with one concrete unblock action.
-8. Check for an existing open PR for the current head branch with `gh pr list --head --state open --json url,number,title,body,baseRefName,headRefName`.
-9. If an open PR already exists with a different base branch than the chosen ``, stop and ask the user whether to correct the PR base.
- - If the user agrees, update the base with `gh pr edit --base ` before any title or body refresh.
- - If the user declines, stop and ask them to rerun `/pr` with the intended base branch.
-10. If an open PR already exists on the chosen base, handle it before generating new metadata.
- - If no commit delta exists against the base branch, reuse the existing PR unchanged and output its URL.
- - Otherwise, show its URL and ask whether to refresh the title and summary.
- - If the user agrees, update only the title and body with `gh pr edit`.
- - If the user declines, reuse the existing PR unchanged.
-11. If no commit delta exists against the base branch, output exactly:
- - `No PR changes to open.`
-12. Infer a Conventional Commit PR title from the full `...HEAD` scope.
- - use the complete branch diff and commit history, not just the latest commit
- - approved types beyond `feat:` and `fix:` are allowed:
- - `build`: production dependencies or build-system changes
- - `chore`: maintenance, admin, or dev-only dependency work
- - `ci`: CI or automation pipeline changes
- - `docs`: documentation-only changes
- - `feat`: a new feature or functionality
- - `fix`: a bug fix for incorrect behaviour
- - `perf`: a performance improvement
- - `refactor`: code changes without behaviour changes
- - `revert`: reverts an earlier change
- - `style`: formatting or style-only clean-up
- - `test`: adds or updates tests
- - make the title a valid Conventional Commit subject suitable for squash merge history
-13. Use a PR body with this exact shape:
-
- ```md
- ## Summary
-
- -
- ```
-
-14. If no open PR exists, create one with `gh pr create --base --title "" --body "<body>"`.
-15. Verify with `gh pr view --json url,number,title,baseRefName,headRefName,state`.
-
-## Rules
-
-- NEVER force push, reset, amend older commits, or change git config.
-- ALWAYS stop for correction when the current branch equals the base branch.
-- ALWAYS stop for user action when push or GitHub auth fails.
-- ALWAYS collect context first.
-- DO use the complete branch diff and commit history, not just the latest commit.
-- ALWAYS make the title a valid Conventional Commit subject suitable for squash merge history.
-
-## Output
-
-Use this exact format for your output when PR creation or reuse succeeds:
-
-```md
-PR URL: <url>
-Title: <final PR title>
-Base branch: <base>
-Head branch: <head>
-State: <state>
-```
diff --git a/additional/commands/review.md b/additional/commands/review.md
deleted file mode 100644
index f4ea3e7..0000000
--- a/additional/commands/review.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-description: Run a report-first senior code review with PR-first context gathering and local fallback modes.
-agent: build
-subtask: true
----
-
-**You are a subagent executing a specific task.**
-
-## Inputs
-
-User input: $ARGUMENTS
-
-- Interpret `$ARGUMENTS` as review scope only.
-- Accepted review scope forms:
- - `#<pr-number>`
- - `uncommitted`
- - `branch`
- - `branch <base-branch>`
-
-## Instructions
-
-1. Resolve the review scope from `$ARGUMENTS`.
-2. If mode is missing, use the question tool:
- - header: Review mode
- - question: Which changes should I review?
- - options:
- - `Pull request (Recommended)` - Review a real GitHub PR by number
- - `Branch diff` - Review current branch changes against a base branch
- - `Uncommitted` - Review staged, unstaged, and untracked changes
-3. If PR review is selected, ask one follow-up question for the PR reference in `#123` form.
-4. If mode is `branch` and base branch is missing, use the question tool:
- - header: Base branch
- - question: Compare current branch against which base branch?
- - options:
- - `main (Recommended)` - Use `main...HEAD`
- - `Custom base branch` - I will provide another branch name
-5. If custom base is selected, ask one follow-up question for the branch name.
-6. Once the review mode and any required follow-up answers are resolved, load the `code-review` skill and follow it strictly.
-7. Pass the resolved review mode, PR reference, and base branch into `code-review`.
-
-## Rules
-
-- ALWAYS keep the accepted review scope forms explicit: `#<pr-number>`, `uncommitted`, `branch`, and `branch <base-branch>`.
-- ALWAYS validate a custom base branch against local refs or `origin/<branch>` refs before proceeding.
-- ALWAYS ask exactly one corrective question when the branch is not found:
- - header: Branch not found
- - question: I could not find that branch. Did you mean the <closest-match>?
- - options:
- - `<closest-match> (Recommended)` - Use the closest matching branch
- - `Enter a different branch` - I will provide another branch name
-- ALWAYS repeat the same branch validation and corrective question flow after `Enter a different branch`.
diff --git a/additional/skills/agentic-commands/SKILL.md b/additional/skills/agentic-commands/SKILL.md
deleted file mode 100644
index 6b45f6f..0000000
--- a/additional/skills/agentic-commands/SKILL.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-name: agentic-commands
-description: Create OpenCode command files for workflow automation. Use when defining slash commands, updating .opencode/commands, or when asked to add/modify OpenCode command templates.
----
-
-# Create Agentic Commands
-
-Write OpenCode command templates that agents can execute reliably in TUI or headless mode.
-
-## Quick Start
-
-```markdown
----
-description: Run tests with coverage and report failures
-agent: build
----
-
-Run the full test suite:
-
-`bun test --coverage`
-
-If tests fail, list each failure with file:line and suggest fixes.
-```
-
-## Core Rules
-
-- Store commands in `.opencode/commands/{name}.md` (global: `~/.config/opencode/commands/{name}.md`).
-- Use `$ARGUMENTS` (or `$1`, `$2`) for user input, `cmd` for shell output, and `@file` to include file contents.
-- Write explicit success/failure handling and verification steps.
-- Avoid destructive shell commands unless the user explicitly asks; if needed, require confirmation.
-- Prefer `subtask: true` for noisy or multi-step workflows.
-- Do not set `model` unless the user requests it.
-
-## References
-
-- [references/examples.md](references/examples.md) - Compact, safe command templates
-- [references/agent-basics.md](references/agent-basics.md) - Agent selection and subtask behavior
diff --git a/additional/skills/agentic-commands/references/agent-basics.md b/additional/skills/agentic-commands/references/agent-basics.md
deleted file mode 100644
index a4835b9..0000000
--- a/additional/skills/agentic-commands/references/agent-basics.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Agent Basics for Commands
-
-Use these pointers when choosing `agent:` or `subtask: true` in command files.
-
-## Built-in Agents
-
-| Agent | Mode | Use Case |
-| --------- | -------- | ---------------------------------------- |
-| `build` | primary | Default agent for most command workflows |
-| `plan` | primary | Planning/analysis only, no writes |
-| `general` | subagent | Research or multi-step assistance |
-| `explore` | subagent | Fast codebase exploration |
-
-## Agent Selection Tips
-
-- Omit `agent` to use the current/default agent.
-- Use `plan` when you need analysis only (no edits).
-- Use specialized agents (like `code-reviewer`) for focused tasks.
-
-## When to Use `subtask: true`
-
-- Long-running workflows
-- Commands that generate large output
-- Tasks you want isolated from the main conversation
diff --git a/additional/skills/agentic-commands/references/examples.md b/additional/skills/agentic-commands/references/examples.md
deleted file mode 100644
index b01da5f..0000000
--- a/additional/skills/agentic-commands/references/examples.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# Command Examples
-
-Short, safe templates for OpenCode `.opencode/commands/*.md` files.
-
-## Example 1: Targeted Test Run
-
-`.opencode/commands/test-filter.md`:
-
-```markdown
----
-description: Run a specific test by name and summarize failures
-agent: build
----
-
-Run tests matching: $ARGUMENTS
-
-`bun test --testNamePattern="$ARGUMENTS" --verbose`
-
-If tests fail, summarize each failure with file:line and likely cause.
-```
-
-## Example 2: Lint and Fix Guidance
-
-`.opencode/commands/lint.md`:
-
-```markdown
----
-description: Run ESLint and report errors with suggested fixes
-agent: build
----
-
-Run ESLint:
-
-`bun run lint`
-
-If errors exist, list each error with file:line and suggested fix.
-```
-
-## Example 3: Code Review (Subtask)
-
-`.opencode/commands/review.md`:
-
-```markdown
----
-description: Review recent changes for quality issues
-agent: code-reviewer
-subtask: true
----
-
-Review changes from the last commit:
-
-`git diff HEAD~1`
-
-Report issues with file:line references and concise recommendations.
-```
diff --git a/additional/skills/agentic-config/SKILL.md b/additional/skills/agentic-config/SKILL.md
deleted file mode 100644
index d26f210..0000000
--- a/additional/skills/agentic-config/SKILL.md
+++ /dev/null
@@ -1,60 +0,0 @@
----
-name: agentic-config
-description: Create or prune AGENTS.md into minimal global steering for agentic tools. Use when initializing projects, reducing redundant context, or updating reusable repo-wide agent rules.
----
-
-# Create Minimal AGENTS.md
-
-AGENTS.md should be a tiny global protocol, not a repository overview.
-
-## Quick Start
-
-```
-1) Read AGENTS.md if present.
-2) Preserve or add the default correction rule.
-3) Remove anything discoverable from source (stack, dirs, scripts, architecture summaries).
-4) Keep only non-discoverable, repo-wide, high-impact constraints.
-```
-
-## Default Rule
-
-Always retain this line, even if it is the only line left in the file:
-
-```markdown
-- When the user corrects your approach with a reusable, global rule for future work, ask whether they want it added to `AGENTS.md`; if they do, load the `agentic-config` skill and update `AGENTS.md`.
-```
-
-## Line Admission Test
-
-Keep every non-default line only if all are true:
-
-- Global: applies to every task/session in this repo.
-- Non-discoverable: the agent cannot reliably infer it from files.
-- Operationally critical: likely to cause mistakes if missing.
-
-If any check fails, remove the line.
-
-## Keep
-
-- The default correction rule above.
-- Environment gotchas the agent cannot infer (path/platform quirks).
-- Hidden operational landmines (legacy coupling, unsafe directories).
-- Repo-wide constraints not encoded elsewhere.
-
-## Remove
-
-- Tech stack, versions, key directories, architecture summaries.
-- Command/script inventories copied from package files.
-- Style guidance already enforced by lint/format/tests.
-- Task-specific workflows that belong in skills or commands.
-
-## Output Contract
-
-- Produce the smallest useful AGENTS.md after the default rule (often 1-20 lines).
-- If no repo-specific constraints qualify, leave AGENTS.md as a one-rule file and explain why.
-- Report removed categories and where that truth is already documented.
-
-## References
-
-- [Research process](references/research-process.md)
-- [Examples](references/examples.md)
diff --git a/additional/skills/agentic-config/references/examples.md b/additional/skills/agentic-config/references/examples.md
deleted file mode 100644
index e39d4f2..0000000
--- a/additional/skills/agentic-config/references/examples.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Minimal AGENTS.md Examples
-
-These examples show protocol-style files. They only include invisible, global constraints.
-
-## Example 1: Environment Gotcha Only
-
-```markdown
-# AGENTS.md
-
-- When the user corrects your approach with a reusable, global rule for future work, ask whether they want it added to `AGENTS.md`; if they do, load the `agentic-config` skill and update `AGENTS.md`.
-- You are running in WSL on Windows; use POSIX paths and avoid Windows drive assumptions.
-```
-
-## Example 2: Hidden Landmine
-
-```markdown
-# AGENTS.md
-
-- When the user corrects your approach with a reusable, global rule for future work, ask whether they want it added to `AGENTS.md`; if they do, load the `agentic-config` skill and update `AGENTS.md`.
-- `legacy/` appears unused but is imported dynamically in production; do not delete or bulk-move it.
-- Always run integration tests with `--no-cache`; cached fixtures cause false positives.
-```
-
-## Example 3: Default Rule Only
-
-```markdown
-# AGENTS.md
-
-- When the user corrects your approach with a reusable, global rule for future work, ask whether they want it added to `AGENTS.md`; if they do, load the `agentic-config` skill and update `AGENTS.md`.
-```
-
-## Anti-Patterns to Avoid
-
-- Full command lists copied from `package.json`.
-- "Project overview" sections (stack, folder map, architecture recap).
-- Generic coding style rules already enforced by tools.
diff --git a/additional/skills/agentic-config/references/research-process.md b/additional/skills/agentic-config/references/research-process.md
deleted file mode 100644
index 23c8b3b..0000000
--- a/additional/skills/agentic-config/references/research-process.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# Pruning-First Process for AGENTS.md
-
-Use this workflow when creating or updating AGENTS.md under the minimal-context model.
-
-## 1) Read the Existing File First
-
-1. Read `AGENTS.md` end-to-end.
-2. Preserve or add the default correction rule before pruning anything else.
-3. Treat every other line as suspect until it passes the admission test.
-
-## Default Rule
-
-Always keep this line, even when no repo-specific constraints survive:
-
-```markdown
-- When the user corrects your approach with a reusable, global rule for future work, ask whether they want it added to `AGENTS.md`; if they do, load the `agentic-config` skill and update `AGENTS.md`.
-```
-
-## 2) Classify Every Line
-
-For each non-default line, decide `keep` or `remove`.
-
-- Keep only if it is global, non-discoverable, and operationally important.
-- Remove if it is discoverable from repository files.
-
-## 3) Remove Common Redundant Buckets
-
-Delete these by default:
-
-- Tech stack and versions
-- Key directories and architecture summaries
-- Command/script inventories from `package.json`/build files
-- General style conventions that tooling already enforces
-
-## 4) Preserve Only Invisible Logic
-
-Typical keepers:
-
-- Environment-specific gotchas the agent cannot infer
-- Hidden coupling and landmines not obvious from code structure
-- Repo-wide constraints not encoded in config/tooling
-
-## 5) Draft the Smallest Useful File
-
-1. Prefer a short protocol-style file.
-2. If no repo-specific line qualifies, keep AGENTS.md as the default rule only.
-3. Push task-scoped guidance into skills/commands.
-
-## 6) Validate Before Finalizing
-
-1. The default rule is present exactly once.
-2. Every other line passes the admission test.
-3. No duplicated truths from source files.
-4. No section filler added to hit a line count target.
-5. Output includes a short keep/remove rationale.
diff --git a/additional/skills/agentic-skills/SKILL.md b/additional/skills/agentic-skills/SKILL.md
deleted file mode 100644
index af8d50c..0000000
--- a/additional/skills/agentic-skills/SKILL.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-name: agentic-skills
-# prettier-ignore
-description: Create OpenCode agent skills with strict progressive disclosure rules. Use when creating skills, updating SKILL.md files, validating skill format, or when user mentions skills, SKILL.md, skill validation, or skill documentation.
----
-
-# Create Agent Skills
-
-Create OpenCode skills that are compact, triggerable, and enforce progressive disclosure with validation.
-
-## Skill Locations
-
-```
-.opencode/skills/{skill-name}/SKILL.md # Project skills
-~/.config/opencode/skills/{skill-name}/SKILL.md # Global skills
-```
-
-## Frontmatter Rules (Level 1)
-
-- `name` matches directory and regex: `^[a-z0-9]+(-[a-z0-9]+)*$`
-- `description` is ONE line, 1-300 chars (warn >200)
-- `description` MUST include `Use when`, `Use for`, or `Use to`
-- `description` is action-oriented and third person
-
-## SKILL.md Body Rules (Level 2)
-
-- Hard limit: 50 lines (frontmatter excluded)
-- 1 code block preferred; warn if >2, error if >3
-- 3-5 sections recommended; warn if >8
-- Long explanations move to `references/`
-
-## References (Level 3)
-
-- Linked with `[text](references/examples.md)` from SKILL.md
-- No nesting beyond depth 1
-- No orphaned reference files
-
-## Workflow
-
-1. Draft SKILL.md using the template in `assets/template.md`
-2. Add detailed docs to `references/`
-3. Run `bun additional/skills/agentic-skills/scripts/validate-skill.mjs <skill-path>`
-4. Fix errors, re-run validation
-5. Use `bun additional/skills/agentic-skills/scripts/doctor-skill.mjs <skill-path>` for multiline description
- fixes
-
-## Validator Expectations
-
-- Detects multiline descriptions and missing trigger phrases
-- Enforces 50-line Level 2 limit
-- Validates reference links and nesting depth
-- Checks keyword overlap between description and body
-
-## References
-
-- [references/checklist.md](references/checklist.md) - Full quality checklist
-- [references/examples.md](references/examples.md) - Short, compliant examples
diff --git a/additional/skills/agentic-skills/assets/template.md b/additional/skills/agentic-skills/assets/template.md
deleted file mode 100644
index 7e3ac1d..0000000
--- a/additional/skills/agentic-skills/assets/template.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# SKILL.md Template
-
-Copy this template to create a new skill. Replace all `{placeholders}` with actual values.
-
----
-
-```markdown
----
-name: {skill-name}
-# prettier-ignore
-description: {Action-oriented summary}. Use when {trigger contexts} or when user mentions {keywords}.
----
-
-# {Skill Title}
-
-{Brief overview: 1-2 sentences.}
-
-## Core Rules
-
-- {Rule 1}
-- {Rule 2}
-- {Rule 3}
-
-## Common Pattern
-
-{Short pattern description (<= 80 words).}
-
-## References
-
-- [references/patterns.md](references/patterns.md) - Advanced patterns
-- [references/examples.md](references/examples.md) - Additional examples
-
-<!--
-PROGRESSIVE DISCLOSURE RULES:
-- Description must be ONE line and <= 300 chars
-- SKILL.md body must be <= 50 lines (frontmatter excluded)
-- Prefer 1 code block (warn if >2, error if >3)
-- Move details to references/
--->
-```
diff --git a/additional/skills/agentic-skills/references/checklist.md b/additional/skills/agentic-skills/references/checklist.md
deleted file mode 100644
index 444c587..0000000
--- a/additional/skills/agentic-skills/references/checklist.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# Skill Quality Checklist
-
-Use this checklist before finalizing or publishing a skill.
-
-## Contents
-
-- [Pre-Creation Checklist](#pre-creation-checklist)
-- [SKILL.md Checklist](#skillmd-checklist)
-- [Progressive Disclosure Checklist](#progressive-disclosure-checklist)
-- [Testing Checklist](#testing-checklist)
-
----
-
-## Pre-Creation Checklist
-
-Before writing the skill:
-
-- [ ] Identified 3-5 concrete usage examples
-- [ ] Listed trigger phrases users would say
-- [ ] Determined what context agent doesn't already have
-- [ ] Planned which resources to include (scripts/references/assets)
-- [ ] Confirmed this isn't duplicate of existing skill
-
----
-
-## SKILL.md Checklist
-
-### Frontmatter
-
-- [ ] `name` is lowercase with single hyphen separators
-- [ ] `name` is 1-64 characters
-- [ ] `name` matches parent directory name
-- [ ] `name` matches regex `^[a-z0-9]+(-[a-z0-9]+)*$`
-- [ ] `description` is one line only
-- [ ] `description` is <= 300 characters (warn > 200)
-- [ ] `description` includes what the skill does
-- [ ] `description` includes `Use when`, `Use for`, or `Use to`
-- [ ] `description` includes natural trigger keywords
-- [ ] `description` is third person and action-oriented
-
-### Body Content (Level 2)
-
-- [ ] Body is <= 50 lines (frontmatter excluded)
-- [ ] 1 code block preferred (warn if >2, error if >3)
-- [ ] 3-5 sections recommended (warn if >8)
-- [ ] No verbose explanations of common knowledge
-- [ ] No README, CHANGELOG, or auxiliary files
-
-### References (Level 3)
-
-- [ ] All `references/*.md` links resolve
-- [ ] No nested references beyond depth 1
-- [ ] No orphaned reference files
-- [ ] Relative paths used: `[file](references/examples.md)`
-
----
-
-## Progressive Disclosure Checklist
-
-### Level 1: Metadata
-
-- [ ] Description is short and triggerable
-- [ ] Description keywords match skill content
-
-### Level 2: SKILL.md
-
-- [ ] Essential workflow only
-- [ ] Extra detail moved to references
-
-### Level 3: Resources
-
-- [ ] References are focused and self-contained
-- [ ] Scripts are tested and executable
-
----
-
-## Testing Checklist
-
-### Before Finalizing
-
-- [ ] Triggered skill with natural phrases from description
-- [ ] Verified correct skill loads (not a similar one)
-- [ ] Tested main workflow end-to-end
-- [ ] Confirmed examples work
-- [ ] Ran validator: `bun additional/skills/agentic-skills/scripts/validate-skill.mjs <path>`
-- [ ] Fixed multiline description with doctor if needed
-
-### After Real Usage
-
-- [ ] Observed agent using the skill on real tasks
-- [ ] Noted any confusion or misses
-- [ ] Updated skill based on observations
-- [ ] Re-tested after changes
diff --git a/additional/skills/agentic-skills/references/examples.md b/additional/skills/agentic-skills/references/examples.md
deleted file mode 100644
index b92f434..0000000
--- a/additional/skills/agentic-skills/references/examples.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Skill Examples
-
-Compact examples that comply with the 50-line Level 2 rule.
-
-## Example 1: Simple Skill
-
-**Directory structure:**
-
-```
-types/
-└── SKILL.md
-```
-
-**SKILL.md:**
-
-```markdown
----
-name: types
-# prettier-ignore
-description: Create TypeScript types and interfaces for data models. Use when defining types, interfaces, data shapes, or when user mentions TypeScript types.
----
-
-# Types
-
-Define type-safe models and interfaces for data shapes.
-
-## Core Rules
-
-- Use `interface` for object shapes
-- Use `type` for unions and computed types
-- Prefer `as const` objects for enum-like values
-
-## References
-
-- [references/examples.md](references/examples.md) - Extended examples
-```
-
-## Example 2: Skill with References
-
-**Directory structure:**
-
-```
-
-hooks/
-├── SKILL.md
-└── references/
- ├── patterns.md
- └── examples.md
-
-```
-
-**SKILL.md:**
-
-```markdown
----
-name: hooks
-# prettier-ignore
-description: Create custom React hooks for reusable logic. Use when creating hooks, extracting shared state, or when user mentions custom hooks.
----
-
-# Hooks
-
-Encapsulate reusable stateful logic in hook functions.
-
-## Core Rules
-
-- Prefix names with `use`
-- Return objects, not arrays
-- Accept options objects for >1 param
-
-## References
-
-- [references/patterns.md](references/patterns.md) - Advanced patterns
-- [references/examples.md](references/examples.md) - Full examples
-```
diff --git a/additional/skills/agentic-skills/scripts/doctor-skill.mjs b/additional/skills/agentic-skills/scripts/doctor-skill.mjs
deleted file mode 100644
index 06cf2ad..0000000
--- a/additional/skills/agentic-skills/scripts/doctor-skill.mjs
+++ /dev/null
@@ -1,106 +0,0 @@
-#!/usr/bin/env bun
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-const args = process.argv.slice(2);
-const targetPath = args[0] ? resolve(args[0]) : process.cwd();
-const skillMdPath = join(targetPath, 'SKILL.md');
-
-if (!existsSync(skillMdPath)) {
- console.error(`SKILL.md not found at ${skillMdPath}`);
- process.exit(1);
-}
-
-const content = readFileSync(skillMdPath, 'utf-8');
-
-if (!content.startsWith('---')) {
- console.error('Missing YAML frontmatter in SKILL.md');
- process.exit(1);
-}
-
-const fixed = fixMultilineDescription(content);
-
-if (fixed === content) {
- console.log('No changes needed.');
- process.exit(0);
-}
-
-writeFileSync(skillMdPath, fixed, 'utf-8');
-console.log(
- 'Fixed multi-line description and added # prettier-ignore if needed.',
-);
-
-function fixMultilineDescription(source) {
- const lines = source.split('\n');
- const out = [];
- let inFrontmatter = false;
- let frontmatterCount = 0;
- let inDescription = false;
- const descriptionParts = [];
- let hasPrettierIgnore = false;
-
- for (let i = 0; i < lines.length; i++) {
- const line = lines[i];
-
- if (line.trim() === '---') {
- frontmatterCount += 1;
- if (frontmatterCount === 2 && inDescription) {
- out.push(`description: ${descriptionParts.join(' ')}`);
- descriptionParts.length = 0;
- inDescription = false;
- }
- inFrontmatter = frontmatterCount === 1;
- out.push(line);
- continue;
- }
-
- if (!inFrontmatter) {
- out.push(line);
- continue;
- }
-
- if (line.trim() === '# prettier-ignore') {
- hasPrettierIgnore = true;
- out.push(line);
- continue;
- }
-
- if (line.match(/^description:/)) {
- const valueMatch = line.match(/^description:\s*(.*)$/);
- const valueOnLine = valueMatch ? valueMatch[1].trim() : '';
- if (!hasPrettierIgnore) {
- out.push('# prettier-ignore');
- hasPrettierIgnore = true;
- }
- if (valueOnLine) {
- out.push(`description: ${valueOnLine}`);
- continue;
- }
- inDescription = true;
- continue;
- }
-
- if (inDescription) {
- if (line.match(/^[a-z_-]+:/)) {
- out.push(`description: ${descriptionParts.join(' ')}`);
- descriptionParts.length = 0;
- inDescription = false;
- out.push(line);
- continue;
- }
- const trimmed = line.trim();
- if (trimmed && !trimmed.startsWith('#')) {
- descriptionParts.push(trimmed);
- }
- continue;
- }
-
- out.push(line);
- }
-
- if (inDescription && descriptionParts.length > 0) {
- out.push(`description: ${descriptionParts.join(' ')}`);
- }
-
- return out.join('\n');
-}
diff --git a/additional/skills/agentic-skills/scripts/validate-skill.mjs b/additional/skills/agentic-skills/scripts/validate-skill.mjs
deleted file mode 100644
index 3d331cc..0000000
--- a/additional/skills/agentic-skills/scripts/validate-skill.mjs
+++ /dev/null
@@ -1,361 +0,0 @@
-#!/usr/bin/env bun
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
-
-const args = process.argv.slice(2);
-const targetPath = args[0] ? resolve(args[0]) : process.cwd();
-const outputJson = args.includes('--json');
-const strict = args.includes('--strict');
-
-const errors = [];
-const warnings = [];
-
-const limits = {
- descriptionMax: 300,
- descriptionWarn: 200,
- bodyLineMax: 50,
- codeBlockWarn: 2,
- codeBlockMax: 3,
- sectionWarn: 8,
-};
-
-function error(message) {
- errors.push(message);
-}
-
-function warn(message) {
- warnings.push(message);
-}
-
-function stripCodeBlocks(content) {
- return content.replace(/```[\s\S]*?```/g, '');
-}
-
-function stripHtmlComments(content) {
- return content.replace(/<!--[\s\S]*?-->/g, '');
-}
-
-function countWords(text) {
- return text
- .trim()
- .split(/\s+/)
- .filter((word) => word.length > 0).length;
-}
-
-function estimateTokens(wordCount) {
- return Math.round(wordCount * 1.3);
-}
-
-function extractKeywords(text) {
- const words = text
- .toLowerCase()
- .replace(/[^\w\s-]/g, ' ')
- .split(/\s+/)
- .filter((word) => word.length > 3);
- const unique = [...new Set(words)];
- const stopwords = new Set([
- 'this',
- 'that',
- 'with',
- 'from',
- 'have',
- 'will',
- 'when',
- 'what',
- 'where',
- 'which',
- 'their',
- 'them',
- 'then',
- 'than',
- 'these',
- 'those',
- 'there',
- ]);
- return unique.filter((word) => !stopwords.has(word));
-}
-
-function hasYamlFrontmatter(content) {
- return content.startsWith('---\n') || content.startsWith('---\r\n');
-}
-
-function extractFrontmatter(content) {
- if (!hasYamlFrontmatter(content)) {
- return {
- name: null,
- description: null,
- body: content,
- rawFrontmatter: '',
- };
- }
- const parts = content.split('---\n');
- if (parts.length < 3) {
- return {
- name: null,
- description: null,
- body: content,
- rawFrontmatter: '',
- };
- }
- const frontmatter = parts[1];
- const body = parts.slice(2).join('---\n');
- const nameMatch = frontmatter.match(/name:\s*(.+)/);
- const name = nameMatch ? nameMatch[1].trim() : null;
- const descMatch = frontmatter.match(/description:\s*(.+?)(?=\n[a-z]+:|$)/s);
- const description = descMatch ? descMatch[1].trim() : null;
- return { name, description, body, rawFrontmatter: frontmatter };
-}
-
-function isDescriptionMultiline(frontmatter) {
- const descLineMatch = frontmatter.match(/^description:\s*(.*)$/m);
- if (!descLineMatch) return false;
- const valueOnLine = descLineMatch[1].trim();
- if (!valueOnLine) return true;
- const lines = frontmatter.split('\n');
- let foundDesc = false;
- for (const line of lines) {
- if (line.match(/^description:/)) {
- foundDesc = true;
- continue;
- }
- if (foundDesc) {
- if (
- line.match(/^\s+\S/) &&
- !line.trim().startsWith('#') &&
- !line.match(/^[a-z_-]+:/)
- ) {
- return true;
- }
- if (line.match(/^[a-z_-]+:/)) {
- break;
- }
- }
- }
- return false;
-}
-
-function validateNameFormat(name, dirName) {
- if (!name) {
- error('SKILL.md frontmatter missing name');
- return;
- }
- if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
- error(`Skill name must match regex ^[a-z0-9]+(-[a-z0-9]+)*$: ${name}`);
- }
- if (name.length > 64) {
- error(`Skill name too long (max 64 chars): ${name.length}`);
- }
- if (name !== dirName) {
- error(`Skill name '${name}' must match directory '${dirName}'`);
- }
-}
-
-function validateDescription(description, frontmatter) {
- if (!description) {
- error('SKILL.md frontmatter missing description');
- return;
- }
- if (isDescriptionMultiline(frontmatter)) {
- error('Description must be single-line YAML (multiline detected)');
- }
- if (description.length > limits.descriptionMax) {
- error(
- `Description too long (${description.length}, max ${limits.descriptionMax})`,
- );
- } else if (description.length > limits.descriptionWarn) {
- warn(
- `Description length ${description.length} (recommended <= ${limits.descriptionWarn})`,
- );
- }
- const lower = description.toLowerCase();
- const hasTrigger =
- lower.includes('use when') ||
- lower.includes('use for') ||
- lower.includes('use to');
- if (!hasTrigger) {
- error('Description missing trigger phrase: Use when/Use for/Use to');
- }
- if (/\b(I can|I will|I help|my|me)\b/i.test(description)) {
- warn('Description uses first person (prefer third person)');
- }
- const actionVerbs =
- /^(create|build|design|analyze|test|validate|generate|process|manage|execute|handle|provide)/i;
- if (!actionVerbs.test(description.trim())) {
- warn('Description is not action-oriented (start with a verb)');
- }
-}
-
-function validateBody(body) {
- const bodyWithoutComments = stripHtmlComments(body);
- const lines = bodyWithoutComments
- .trim()
- .split('\n')
- .filter((line) => line.length > 0);
- const lineCount = lines.length;
- if (lineCount > limits.bodyLineMax) {
- error(
- `SKILL.md body has ${lineCount} lines (max ${limits.bodyLineMax})`,
- );
- }
- const codeBlocks = (body.match(/```[\s\S]*?```/g) || []).length;
- if (codeBlocks > limits.codeBlockMax) {
- error(
- `SKILL.md has ${codeBlocks} code blocks (max ${limits.codeBlockMax})`,
- );
- } else if (codeBlocks > limits.codeBlockWarn) {
- warn(
- `SKILL.md has ${codeBlocks} code blocks (recommended <= ${limits.codeBlockWarn})`,
- );
- }
- const sections = (body.match(/^#{1,6}\s/gm) || []).length;
- if (sections > limits.sectionWarn) {
- warn(
- `SKILL.md has ${sections} sections (recommended <= ${limits.sectionWarn})`,
- );
- }
- const wordCount = countWords(body);
- const estimatedTokens = estimateTokens(wordCount);
- return { lineCount, codeBlocks, sections, wordCount, estimatedTokens };
-}
-
-function validateReferences(skillPath, body) {
- const referencesDir = join(skillPath, 'references');
- const skillContent = stripCodeBlocks(body);
- const referencePattern = /\[([^\]]+)\]\((references\/[^)]+\.md)\)/g;
- const matches = [...skillContent.matchAll(referencePattern)];
-
- const referencedFiles = matches.map((match) => match[2]);
- const missing = [];
- const nesting = [];
-
- for (const filePath of referencedFiles) {
- const fullPath = join(skillPath, filePath);
- if (!existsSync(fullPath)) {
- missing.push(filePath);
- error(`Referenced file not found: ${filePath}`);
- continue;
- }
- const depth = referenceDepth(skillPath, filePath);
- if (depth > 1) {
- warn(
- `Reference nesting depth ${depth} for ${filePath} (recommended 1)`,
- );
- }
- nesting.push({ file: filePath, depth });
- }
-
- if (existsSync(referencesDir)) {
- const files = readdirSync(referencesDir).filter((file) =>
- file.endsWith('.md'),
- );
- for (const file of files) {
- const referenced = referencedFiles.some((ref) =>
- ref.endsWith(file),
- );
- if (!referenced) {
- warn(`Reference file not linked from SKILL.md: ${file}`);
- }
- }
- }
-
- return { referencedFiles, missing, nesting };
-}
-
-function referenceDepth(skillPath, filePath, visited = new Set()) {
- if (visited.has(filePath)) return 0;
- visited.add(filePath);
- const fullPath = join(skillPath, filePath);
- if (!existsSync(fullPath)) return 0;
- const content = stripCodeBlocks(readFileSync(fullPath, 'utf-8'));
- const referencePattern = /\[([^\]]+)\]\((references\/[^)]+\.md)\)/g;
- const matches = [...content.matchAll(referencePattern)];
- if (matches.length === 0) return 1;
- let maxDepth = 1;
- for (const match of matches) {
- const nestedDepth = referenceDepth(
- skillPath,
- match[2],
- new Set(visited),
- );
- maxDepth = Math.max(maxDepth, 1 + nestedDepth);
- }
- return maxDepth;
-}
-
-function validateKeywords(description, body) {
- const descKeywords = extractKeywords(description);
- const bodyKeywords = extractKeywords(body);
- if (descKeywords.length < 5 || bodyKeywords.length < 5) return;
- const overlap = descKeywords.filter((keyword) =>
- bodyKeywords.includes(keyword),
- );
- const overlapRatio = overlap.length / descKeywords.length;
- if (overlapRatio < 0.3) {
- warn(
- `Low keyword overlap between description and body (${Math.round(overlapRatio * 100)}%)`,
- );
- }
-}
-
-function validateSkillPath(skillPath) {
- const stats = statSync(skillPath);
- if (!stats.isDirectory()) {
- error(`Path is not a directory: ${skillPath}`);
- return null;
- }
- const skillMdPath = join(skillPath, 'SKILL.md');
- if (!existsSync(skillMdPath)) {
- error('SKILL.md not found in skill directory');
- return null;
- }
- const content = readFileSync(skillMdPath, 'utf-8');
- if (!hasYamlFrontmatter(content)) {
- error('Missing YAML frontmatter in SKILL.md');
- }
- const { name, description, body, rawFrontmatter } =
- extractFrontmatter(content);
- const dirName = basename(skillPath);
-
- validateNameFormat(name, dirName);
- validateDescription(description, rawFrontmatter);
- const bodyStats = validateBody(body);
- validateReferences(skillPath, body);
- if (description) {
- validateKeywords(description, body);
- }
-
- return { name, description, bodyStats };
-}
-
-if (!existsSync(targetPath)) {
- error(`Path does not exist: ${targetPath}`);
-}
-
-const result = existsSync(targetPath) ? validateSkillPath(targetPath) : null;
-
-const report = {
- path: targetPath,
- valid: errors.length === 0,
- errors,
- warnings,
- stats: result?.bodyStats ?? null,
-};
-
-if (outputJson) {
- console.log(JSON.stringify(report, null, 2));
- process.exit(report.valid && !(strict && warnings.length) ? 0 : 1);
-}
-
-if (errors.length > 0) {
- console.log('Errors:');
- errors.forEach((message) => console.log(`- ${message}`));
-}
-if (warnings.length > 0) {
- console.log('Warnings:');
- warnings.forEach((message) => console.log(`- ${message}`));
-}
-if (errors.length === 0) {
- console.log('Skill is valid.');
-}
-
-process.exit(report.valid && !(strict && warnings.length) ? 0 : 1);
diff --git a/additional/skills/agentic-subagents/SKILL.md b/additional/skills/agentic-subagents/SKILL.md
deleted file mode 100644
index 01c305e..0000000
--- a/additional/skills/agentic-subagents/SKILL.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-name: agentic-subagents
-description: Create OpenCode subagents for automatic routing and safe workflows. Use when defining .opencode/agents, descriptions, and permissions.
----
-
-# Create OpenCode Subagents
-
-## Quick Start
-
-Create `.opencode/agents/code-reviewer.md`:
-
-```markdown
----
-description: Reviews code for bugs, security, and maintainability without changes. Automatically invoke this agent after code changes or when the user requests review. Use when reviewing diffs, PRs, refactors, or audits.
-mode: subagent
-temperature: 0.1
-permission:
- edit: deny
- bash:
- '*': deny
- 'git diff*': allow
- 'git log*': allow
- 'git status*': allow
----
-
-You are a code reviewer. Provide prioritized findings with file:line references and fixes.
-```
-
-## Rules
-
-- Store subagents in `.opencode/agents/` with kebab-case filenames; set `mode: subagent`.
-- Treat `description` as the routing contract: capability + auto-invoke trigger + "Use when" clause.
-- Prefer `permission` over legacy `tools`; grant only the tools the workflow needs.
-- Use `steps` to cap iteration loops; include exit criteria for test/lint/run loops.
-- Keep each subagent focused on one workflow; delegate for multi-specialist tasks.
-
-## References
-
-- [references/agent-files.md](references/agent-files.md)
-- [references/description-routing.md](references/description-routing.md)
-- [references/permission-recipes.md](references/permission-recipes.md)
-- [references/advanced.md](references/advanced.md)
-- [references/patterns.md](references/patterns.md)
-- [references/examples.md](references/examples.md)
diff --git a/additional/skills/agentic-subagents/references/advanced.md b/additional/skills/agentic-subagents/references/advanced.md
deleted file mode 100644
index c2fba4e..0000000
--- a/additional/skills/agentic-subagents/references/advanced.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# Advanced Patterns
-
-## Task Delegation Controls (Optional)
-
-Use `permission.task` to restrict which subagents can be invoked via the Task tool.
-Only use this when you need a strict orchestrator.
-
-```yaml
-permission:
- task:
- '*': deny
- 'code-reviewer': allow
- 'test-fixer': allow
- 'security-auditor': ask
-```
-
-## Hidden Internal Helpers
-
-Hide internal subagents from the @ menu:
-
-```yaml
-hidden: true
-```
-
-## Iteration Limits
-
-Use `steps` to cap agentic loops on costly workflows:
-
-```yaml
-steps: 25
-```
diff --git a/additional/skills/agentic-subagents/references/agent-files.md b/additional/skills/agentic-subagents/references/agent-files.md
deleted file mode 100644
index d01cf77..0000000
--- a/additional/skills/agentic-subagents/references/agent-files.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Subagent Files (.opencode/agents)
-
-Create each subagent as a markdown file in `.opencode/agents/`.
-The filename (kebab-case) becomes the agent name for `@` mentions.
-
-## Required Frontmatter
-
-- `description` (required): routing contract for auto-delegation
-- `mode: subagent`
-
-## Common Frontmatter
-
-- `temperature` (defaults vary by model)
-- `model` (optional override; otherwise inherits from invoker)
-- `steps` (max agentic iterations; use for iterative workflows)
-- `permission` (preferred over legacy `tools`)
-
-## Notes
-
-- Prefer `permission` over deprecated `tools` booleans.
-- Use kebab-case names like `code-reviewer.md`, `test-fixer.md`.
diff --git a/additional/skills/agentic-subagents/references/description-routing.md b/additional/skills/agentic-subagents/references/description-routing.md
deleted file mode 100644
index 0d93adc..0000000
--- a/additional/skills/agentic-subagents/references/description-routing.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Routing-Friendly Descriptions
-
-OpenCode auto-invokes subagents based on `description`. Keep it short and aligned to user phrasing.
-
-## Recommended Format
-
-1. Capability statement
-2. Auto-invoke trigger
-3. "Use when" clause with 4-8 high-signal keywords
-
-Example:
-
-```
-description: Runs tests and fixes failures until all pass. Automatically invoke this agent when tests fail or after code changes. Use when fixing tests, debugging failures, or stabilizing CI.
-```
-
-## Avoid
-
-- Long keyword lists or unrelated terms
-- Implementation detail in description
-- Vague triggers like "use when needed"
diff --git a/additional/skills/agentic-subagents/references/examples.md b/additional/skills/agentic-subagents/references/examples.md
deleted file mode 100644
index 36db984..0000000
--- a/additional/skills/agentic-subagents/references/examples.md
+++ /dev/null
@@ -1,529 +0,0 @@
-# Full Agent Examples
-
-Complete, production-ready agent configurations demonstrating best practices.
-
-## Example 1: Code Reviewer (Read-Only Pattern)
-
-`.opencode/agents/code-reviewer.md`:
-
-````markdown
----
-description: Reviews code for quality, security, and best practices without making changes. Automatically invoke this agent after code changes. Use for code review, quality checks, or when user mentions reviewing code, checking security, or auditing quality.
-mode: subagent
-temperature: 0.1
-permission:
- edit: deny
- bash:
- '*': deny
- 'git diff*': allow
- 'git log*': allow
- 'git status*': allow
----
-
-You are a senior code reviewer specializing in Astro and modern web applications.
-
-Review focus areas:
-
-1. **Security**
- - Exposed secrets, insecure storage
- - Improper deep link handling
- - Insecure data transmission
-
-2. **Type Safety**
- - Full TypeScript coverage
- - No `any` types, proper type annotations
- - Correct use of generics
-
-3. **Testing**
- - Adequate coverage (>=90%)
- - Quality assertions, edge case coverage
-
-4. **Performance**
- - Unnecessary re-renders
- - Missing memoization (useMemo, useCallback, React.memo)
- - Heavy computations in render path
- - Large bundle size concerns
-
-5. **Astro/Web Patterns**
- - Server-first rendering with selective `client:*` hydration
- - Clear server/client boundaries and minimal shipped JS
- - Proper use of content collections and `astro:assets`
- - Avoid `client:only` unless SSR is not possible
-
-Output format:
-
-## Critical Issues
-
-**File**: `path/to/file.tsx:123`
-**Issue**: [Clear description]
-**Impact**: [Why this matters]
-**Fix**:
-
-```tsx
-// Suggested implementation
-```
-````
-
-**Reasoning**: [Why this is better]
-
----
-
-## High Priority
-
-[Same format]
-
----
-
-## Suggestions
-
-[Same format]
-
----
-
-## Good Practices
-
-**File**: `path/to/file.tsx`
-**Observation**: [What's well implemented]
-**Why it works**: [Pattern explanation]
-
----
-
-## Summary
-
-- Total files reviewed: X
-- Critical issues: X
-- High priority: X
-- Suggestions: X
-
-**Priority actions**: [Top 3 things to fix first]
-
-Guidelines:
-
-- Always include file paths and line numbers
-- Explain the "why" behind recommendations
-- Acknowledge good patterns
-- You **cannot make changes** - only provide feedback
-
-````
-
-## Example 2: Test Fixer (Evaluator-Optimizer Pattern)
-
-`.opencode/agents/test-fixer.md`:
-
-```markdown
----
-description: Runs tests iteratively and fixes failures until all tests pass with adequate coverage. Automatically invoke this agent after code changes. Use when fixing tests, debugging failures, or ensuring test suite is green.
-mode: subagent
-temperature: 0.2
-steps: 30
-permission:
- edit: allow
- bash:
- "*": deny
- "bun test*": allow
----
-
-You are a test fixing specialist for Astro and web applications.
-
-Workflow:
-
-1. **Run Tests**
- ```bash
- bun test --coverage
-````
-
-2. **Evaluate Results** (ground truth)
- - If all pass with >=90% coverage -> Report success and exit
- - If failures -> Continue to step 3
-
-3. **Fix Failures**
- For each failing test:
- - Identify test file and failing assertion
- - Analyze failure reason
- - Determine root cause:
- - Code bug -> Fix in source files
- - Test bug -> Fix in test files
- - Missing mock -> Add appropriate mock
- - Implement the fix
- - Explain what was fixed and why
-
-4. **Re-run Tests** (verify against ground truth)
-
- ```bash
- bun test --coverage
- ```
-
- Repeat from step 2.
-
-5. **Final Report**
- After all tests pass:
-
- ```
- All X tests passing
- Coverage: X% (threshold: 90%)
-
- Summary of fixes:
- - [What was fixed and why]
- ```
-
-Exit criteria:
-
-- All tests passing
-- Coverage >=90%
-
-Guidelines:
-
-- Fix root causes, not symptoms
-- Never remove tests to make them pass
-- Never use `.skip()` as a solution
-- Maintain or improve coverage
-- Follow project conventions
-
-````
-
-## Example 3: Quality Auditor (Multi-Step Evaluator Pattern)
-
-`.opencode/agents/quality-auditor.md`:
-
-```markdown
----
-description: Runs all quality checks (TypeScript, ESLint, Prettier, tests, coverage) and fixes issues iteratively. Automatically invoke this agent before committing. Use when running quality checks, ensuring code quality, or when user mentions quality, checks, or linting.
-mode: subagent
-temperature: 0.2
-steps: 40
-permission:
- edit: allow
- bash:
- "*": deny
- "bun run lint*": allow
- "bun run format*": allow
- "bun test*": allow
- "bunx tsc*": allow
----
-
-You are a quality auditor for Astro and web applications.
-
-Execute checks in order, fixing issues iteratively:
-
-**Step 1: TypeScript**
-```bash
-bunx tsc --noEmit
-````
-
-Fix type errors until clean.
-
-**Step 2: ESLint**
-
-```bash
-bun run lint
-```
-
-Fix linting errors until clean.
-
-**Step 3: Prettier**
-
-```bash
-bunx prettier --check .
-```
-
-If issues found, run `bunx prettier --write .`
-
-**Step 4: Tests**
-
-```bash
-bun test --coverage
-```
-
-Ensure all pass with >=90% coverage.
-
-For each step:
-
-1. Run the check
-2. If issues found, fix them
-3. Re-run until clean
-4. Move to next step
-
-Exit criteria:
-
-- All four steps passing
-- Coverage >=90%
-
-Final report:
-
-```
-Quality Audit Complete
-
-TypeScript: Clean
-ESLint: Clean
-Prettier: Formatted
-Tests: All passing, X% coverage
-
-Summary of fixes:
-- [Brief list]
-
-The codebase meets all quality standards.
-```
-
-Guidelines:
-
-- Never skip tests with `.skip()`
-- Never lower standards to pass checks
-- Always fix root causes
-- Run full workflow, don't stop early
-
-````
-
-## Example 4: Security Auditor (Read-Only Specialist)
-
-`.opencode/agents/security-auditor.md`:
-
-```markdown
----
-description: Performs security audits identifying vulnerabilities, insecure patterns, and data exposure risks. Automatically invoke this agent after implementing auth, payments, or sensitive data storage. Use when doing security review, vulnerability scanning, or compliance checks.
-mode: subagent
-temperature: 0.1
-permission:
- edit: deny
- bash:
- "*": deny
- "bun audit*": allow
- "bun outdated*": allow
----
-
-You are a security expert specializing in web application security.
-
-Audit checklist:
-
-## 1. Data Handling
-- Secrets or API keys exposed in client bundles
-- Sensitive data stored in localStorage/sessionStorage
-- Unsafe handling of user-generated content
-
-## 2. Network Security
-- HTTP instead of HTTPS
-- Missing CSP or unsafe inline scripts
-- Unvalidated external requests from server code
-
-## 3. Authentication
-- Insecure cookie flags (HttpOnly, Secure, SameSite)
-- Token exposure in client code
-- Missing CSRF protection for form submissions
-
-## 4. Routing & Rendering
-- XSS risks in Markdown/MDX or raw HTML rendering
-- Unsafe use of `set:html` without sanitization
-- Leaky server-only data into client islands
-
-## 5. Dependencies
-- Vulnerable dependencies (bun audit)
-- Outdated packages with known CVEs
-
-## 6. Build/Deployment
-- Debug code in production
-- Console.log with sensitive data
-- Public source maps when not intended
-
-Output format:
-
-## Critical Vulnerabilities
-
-**File**: `path/to/file.tsx:123`
-**Issue**: API key exposed in source code
-**Impact**: Attacker can access backend services
-**Fix**: Move to server-only env vars and avoid client exposure
-**CVSS**: 9.8 (Critical)
-
-## High Risk
-
-[Significant security concerns]
-
-## Medium Risk
-
-[Issues requiring attention]
-
-## Low Risk / Best Practices
-
-[Minor improvements]
-
-## Security Strengths
-
-[Good security practices observed]
-````
-
-## Example 5: Feature Builder (Skill-Enhanced Pattern)
-
-`.opencode/agents/feature-builder.md`:
-
-````markdown
----
-description: Builds complete Astro features end-to-end (pages, layouts, components, islands, tests). Automatically invoke this agent when a task requires implementing a full feature with multiple integrated parts. Use when adding features, building user flows, or creating new routes.
-mode: subagent
-temperature: 0.3
-permission:
- edit: allow
- bash: ask
-skills:
- - astro-component
- - astro-page
- - astro-layout
- - astro-test
----
-
-You are a feature builder for Astro applications.
-
-You have specialized skills loaded for creating:
-
-- Components (Astro/React UI in components/)
-- Pages (routes in src/pages/)
-- Layouts (shared shells in src/layouts/)
-- Tests (unit/integration tests alongside source files)
-
-Workflow:
-
-1. **Understand Requirements**
- Clarify feature scope and acceptance criteria.
-
-2. **Create Types**
- TypeScript interfaces for data structures.
-
-3. **Create Hooks**
- Custom hooks for business logic and state.
-
-4. **Create Components**
- Reusable UI components with proper styling.
-
-5. **Create Page**
- Astro route integrating components and layouts.
-
-6. **Write Tests**
- Unit tests for hooks, component tests for UI.
-
-7. **Run Quality Checks**
- ```bash
- bun run checks
- ```
-
-Guidelines:
-
-- Follow patterns from loaded skills
-- Use strict TypeScript everywhere
-- Write tests for all new code
-- Follow the project's styling conventions (e.g. Tailwind classes when available)
-- Handle loading and error states
-````
-
-## Example 6: Debugger with Hooks
-
-`.opencode/agents/debugger.md`:
-
-```markdown
----
-description: Debugging specialist for errors, test failures, and unexpected behavior. Automatically invoke this agent when encountering issues.
-mode: subagent
-temperature: 0.3
-steps: 25
----
-
-You are an expert debugger specializing in Astro and web applications.
-
-Workflow:
-
-1. **Capture Context**
- - Error message and stack trace
- - Reproduction steps
- - Recent changes (git log)
-
-- Runtime (SSR/static, browser, deployment target)
-
-2. **Form Hypothesis**
- - Identify likely failure points
- - Check recent code changes
- - Review related tests
-
-- Check for hydration mismatches or server/client boundary issues
-
-3. **Isolate Issue**
- - Add strategic console.log statements
-
-- Use React/Astro devtools if UI issue
- - Check network requests if API issue
- - Narrow down to specific code
-
-4. **Implement Fix**
- - Make minimal, targeted change
- - Fix root cause, not symptom
-
-5. **Verify Solution**
- - Run relevant tests
- - Confirm error resolved
- - Check for regressions
- - Test on affected platform(s)
-
-Output for each issue:
-
-- **Root cause**: Why it happened
-- **Evidence**: How you identified it
-- **Fix**: What was changed
-- **Prevention**: How to avoid in future
-
-Guidelines:
-
-- Focus on understanding before fixing
-- Make minimal changes
-- Verify fixes with tests
-- Consider runtime-specific behavior (SSR vs client)
-- Restart dev server and clear browser cache if caching suspected
-```
-
-## Example 7: Documentation Writer (Path-Restricted)
-
-`.opencode/agents/docs-writer.md`:
-
-```markdown
----
-description: Writes and maintains project documentation with clear explanations and examples. Use for creating docs, updating README, or documenting features.
-mode: subagent
-temperature: 0.4
-permission:
- bash: deny
- edit:
- 'docs/*': allow
- 'README.md': allow
- 'CHANGELOG.md': allow
- '*.md': ask
- '*': deny
----
-
-You are a technical documentation specialist.
-
-Scope:
-
-- Can edit files in docs/ directory
-- Can edit README.md and CHANGELOG.md
-- Must ask before editing other .md files
-- Cannot edit source code files
-
-Focus on:
-
-- Clear explanations of functionality
-- Step-by-step setup instructions
-- Code examples with context
-- Runtime-specific notes (SSR vs static, deployment targets)
-- Troubleshooting guidance
-
-Format guidelines:
-
-- Use headings for structure
-- Code blocks with language specification
-- Lists for steps or features
-- Tables for comparisons
-- Screenshots for UI documentation
-
-Guidelines:
-
-- Write for the target audience
-- Prefer concise over verbose
-- Include examples for complex concepts
-- Keep formatting consistent
-- Note Astro SSR vs static output differences
-```
diff --git a/additional/skills/agentic-subagents/references/patterns.md b/additional/skills/agentic-subagents/references/patterns.md
deleted file mode 100644
index 9113acf..0000000
--- a/additional/skills/agentic-subagents/references/patterns.md
+++ /dev/null
@@ -1,364 +0,0 @@
-# Workflow Patterns for Subagents
-
-Patterns for designing subagents. The goal is to keep each subagent focused, easy to route to via `description`, and safe via `permission`.
-
-## Pattern 1: Evaluator-Optimizer (Iterative)
-
-**From Anthropic's "Building Effective Agents"**: One LLM generates a response while another (or the same one) provides evaluation and feedback in a loop.
-
-**Best for:** Test fixing, quality auditing, code refinement, any task with verifiable success criteria.
-
-**Why it works:** Agents perform best when they have clear targets to iterate against. Ground truth feedback (test results, linter output) allows objective progress measurement.
-
-```markdown
----
-description: Runs tests and fixes failures iteratively until all pass. Automatically invoke this agent after code changes. Use when fixing tests, debugging failures, or ensuring test suite passes.
-mode: subagent
-temperature: 0.2
-steps: 30
-permission:
- edit: allow
- bash:
- '*': deny
- 'bun test*': allow
- 'bunx tsc*': allow
----
-
-You are a test fixing specialist.
-
-Workflow:
-
-1. **Run Tests**
- Execute the test suite to identify failures.
-
-2. **Evaluate Results** (ground truth)
- - If all pass -> Report success and exit
- - If failures -> Continue to step 3
-
-3. **Fix Failures**
- For each failing test:
- - Identify root cause (code bug vs test bug)
- - Implement targeted fix
- - Explain the fix
-
-4. **Re-run Tests** (verify against ground truth)
- Repeat from step 2.
-
-Exit criteria:
-
-- All tests passing
-- Coverage >=90%
-
-Guidelines:
-
-- Fix root causes, not symptoms
-- Never remove tests to make them pass
-- Never use .skip() as a solution
-
-Final report:
-All X tests passing
-Coverage: X%
-Summary of fixes applied
-```
-
-**Key characteristics:**
-
-- Ground truth feedback loop (test results)
-- Clear exit criteria
-- Explicit anti-patterns
-
-## Pattern 2: Read-Only Reviewer
-
-**Best for:** Code review, security audits, architecture analysis, any task requiring analysis without modification.
-
-**Why it works:** Tool restrictions enforce behavior that matches intent. Cannot accidentally make changes while reviewing.
-
-```markdown
----
-description: Reviews code for quality, security, and best practices without making changes. Automatically invoke this agent after code changes. Use for code review or when user mentions reviewing code.
-mode: subagent
-temperature: 0.1
-permission:
- edit: deny
- bash:
- '*': deny
- 'git diff*': allow
- 'git log*': allow
----
-
-You are a senior code reviewer.
-
-Review focus areas:
-
-1. **Security** - Data exposure, insecure storage, deep link handling
-2. **Type Safety** - Full TypeScript coverage, no `any` types
-3. **Testing** - Adequate coverage, edge cases
-4. **Performance** - Unnecessary re-renders; avoid manual memoization unless justified
-5. **Architecture** - SOLID, DRY, Astro/web patterns
-
-Output format:
-
-## Critical Issues
-
-**File**: `path/to/file.tsx:123`
-**Issue**: [Description]
-**Impact**: [Why this matters]
-**Fix**: [Code example]
-
-## High Priority
-
-[Same format]
-
-## Suggestions
-
-[Same format]
-
-## Good Practices
-
-[What's working well]
-
-## Summary
-
-- Total files reviewed: X
-- Critical issues: X
-- Priority actions: [Top 3]
-
-Guidelines:
-
-- Always include file paths and line numbers
-- Explain the "why" behind recommendations
-- Acknowledge good patterns
-```
-
-**Key characteristics:**
-
-- All edit tools disabled
-- Structured output format
-- Low temperature for consistency
-
-## Pattern 3: Orchestrator-Workers
-
-**From Anthropic's "Building Effective Agents"**: A central LLM dynamically breaks down tasks, delegates to workers, and synthesizes results.
-
-**Best for:** Complex multi-step workflows requiring different specialists.
-
-**Why it works:** Separates coordination from execution. Each worker has focused context and can be optimized independently.
-
-```markdown
----
-description: Orchestrates complex workflows by coordinating specialized subagents. Automatically invoke this agent for multi-step tasks needing multiple specialists. Use when planning work across review, debugging, tests, or security.
-mode: subagent
-temperature: 0.3
-permission:
- task:
- '*': deny
- 'code-reviewer': allow
- 'test-fixer': allow
- 'security-auditor': ask
----
-
-You are a workflow orchestrator managing complex development tasks.
-
-Available specialists:
-
-- code-reviewer: Code quality and best practices
-- test-fixer: Fix failing tests iteratively
-- security-auditor: Security vulnerability assessment
-
-Workflow:
-
-1. **Analyze Task**
- Break down into subtasks.
- Identify which specialists are needed.
-
-2. **Delegate to Specialists**
- Invoke appropriate subagents with clear, focused instructions.
- Provide each with specific scope.
-
-3. **Synthesize Results**
- Gather findings from all subagents.
- Identify conflicts or dependencies.
- Create comprehensive solution.
-
-4. **Verify**
- Ensure all aspects addressed.
- Run final validation if needed.
-
-Guidelines:
-
-- Delegate to specialists rather than doing work yourself
-- Provide clear, focused instructions to each subagent
-- Synthesize results into cohesive output
-```
-
-**Key characteristics:**
-
-- Task permissions control which subagents can be invoked
-- Delegates rather than executes
-- Synthesizes results from multiple specialists
-
-## Pattern 4: Exploration Agent
-
-**From OpenCode's built-in agents**: Fast, read-only agent for codebase discovery.
-
-**Best for:** Finding files, understanding architecture, answering questions about the codebase.
-
-**Why it works:** Isolated context keeps exploration out of main conversation. Compressed findings returned to parent.
-
-```markdown
----
-description: Fast codebase exploration and pattern discovery. Automatically invoke this agent when you need quick file/pattern discovery. Use when searching the codebase, understanding architecture, or finding implementations.
-mode: subagent
-temperature: 0.3
-permission:
- edit: deny
- bash:
- '*': deny
----
-
-You are a codebase exploration specialist.
-
-Your role:
-
-- Quickly discover relevant files and patterns
-- Understand codebase architecture
-- Find specific implementations
-- Return compressed, relevant findings
-
-Workflow:
-
-1. Understand the search goal
-2. Use Glob to find relevant files
-3. Use Grep to search for keywords
-4. Read key files to understand implementation
-5. Return compressed findings with file references
-
-Output format:
-
-## Findings
-
-### Relevant Files
-
-- `path/to/file.tsx:123` - Brief description
-- `path/to/other.tsx:45` - Brief description
-
-### Key Patterns
-
-- Pattern 1: Explanation
-- Pattern 2: Explanation
-
-### Recommendations
-
-- Next steps or suggestions
-```
-
-**Key characteristics:**
-
-- Read-only for safety
-- Fast discovery focus
-- Compressed output to avoid context pollution
-
-## Pattern 5: Path-Restricted Writer
-
-**Best for:** Documentation, focused file updates, scoped modifications.
-
-**Why it works:** Permissions enforce scope boundaries, preventing unintended changes outside designated areas.
-
-```markdown
----
-description: Writes and maintains documentation with clear explanations. Automatically invoke this agent when documentation updates are needed. Use when creating docs, updating README, or documenting features.
-mode: subagent
-temperature: 0.4
-permission:
- bash: deny
- edit:
- 'docs/*': allow
- 'README.md': allow
- '*.md': ask
- '*': deny
----
-
-You are a technical documentation specialist.
-
-Scope restrictions:
-
-- Can edit files in docs/ directory
-- Can edit README.md
-- Must ask before editing other .md files
-- Cannot edit source code files
-
-Guidelines:
-
-- Write clear, concise documentation
-- Include code examples
-- Use proper markdown formatting
-- Structure content logically
-```
-
-**Key characteristics:**
-
-- Path-specific permissions
-- Cannot touch source code
-- Clear scope boundaries
-
-## Pattern 6: Debugger with Hooks
-
-## Pattern 6: Skill-Enhanced Agent
-
-**Best for:** Agents that need specialized knowledge loaded at startup.
-
-**Why it works:** Skills provide domain-specific instructions without bloating the agent's system prompt.
-
-```markdown
----
-description: Builds Astro features following best practices. Automatically invoke this agent when a task requires implementing a full feature across pages, layouts, components, and tests. Use when implementing new functionality or user flows.
-mode: subagent
-temperature: 0.3
-permission:
- edit: allow
- bash: ask
-skills:
- - astro-component
- - astro-page
- - astro-layout
- - astro-test
----
-
-You are a feature builder for Astro applications.
-
-You have specialized skills loaded for:
-
-- Creating Components (Astro/React UI)
-- Creating Pages (routes in src/pages/)
-- Creating Layouts (shared shells)
-- Writing Tests (unit/integration tests)
-
-Follow the patterns from your loaded skills when implementing features.
-
-Workflow:
-
-1. Understand feature requirements
-2. Create TypeScript types/interfaces
-3. Create custom hooks for logic
-4. Create reusable components
-5. Create screen integrating components
-6. Write tests
-7. Run quality checks
-```
-
-**Key characteristics:**
-
-- Skills loaded at startup (not invoked on-demand)
-- Agent has specialized knowledge available
-- Follows patterns from loaded skills
-
-## Choosing the Right Pattern
-
-| Pattern | Use When | Key Feature |
-| -------------------- | ------------------------------- | -------------------------- |
-| Evaluator-Optimizer | Iterating to verifiable success | Ground truth feedback loop |
-| Read-Only Reviewer | Analysis without modification | Tool restrictions |
-| Orchestrator-Workers | Complex multi-specialist tasks | Task delegation |
-| Exploration | Finding and understanding code | Context isolation |
-| Path-Restricted | Scoped file modifications | Permission boundaries |
-| Skill-Enhanced | Domain expertise needed | Skills loaded at startup |
diff --git a/additional/skills/agentic-subagents/references/permission-recipes.md b/additional/skills/agentic-subagents/references/permission-recipes.md
deleted file mode 100644
index ec03ba9..0000000
--- a/additional/skills/agentic-subagents/references/permission-recipes.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# Permission Recipes
-
-Use `permission` to align tool access with the workflow. Grant only what the agent needs.
-
-## Read-Only Reviewer
-
-```yaml
-permission:
- edit: deny
- bash:
- '*': deny
- 'git diff*': allow
- 'git log*': allow
- 'git status*': allow
-```
-
-## Test Runner (Read-Only)
-
-```yaml
-permission:
- edit: deny
- bash:
- '*': deny
- 'bun test*': allow
- 'bunx tsc*': allow
-```
-
-## Test Fixer (Edit + Test)
-
-```yaml
-permission:
- edit: allow
- bash:
- '*': deny
- 'bun test*': allow
- 'bunx tsc*': allow
-```
-
-## Feature Builder (Full Build)
-
-```yaml
-permission:
- edit: allow
- bash: ask
-```
-
-## Docs Writer (Path-Restricted)
-
-```yaml
-permission:
- edit:
- 'docs/*': allow
- 'README.md': allow
- '*.md': ask
- '*': deny
- bash: deny
-```
-
-## Notes
-
-- `edit` covers all file modifications (edit/write/patch). Use it instead of `write`.
-- Put "\*" first; last matching rule wins.
diff --git a/additional/skills/code-review/SKILL.md b/additional/skills/code-review/SKILL.md
deleted file mode 100644
index af5230f..0000000
--- a/additional/skills/code-review/SKILL.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-name: code-review
-# prettier-ignore
-description: Reviews code changes for senior-level PR feedback with parallel reviewer passes, disprove-first validation, and exact report output. Use when reviewing PR or local changes.
----
-
-# Code Review
-
-Review diffs like a senior engineer. Stay evidence-first. Stay merge-relevant.
-
-## Instructions
-
-1. Resolve review scope and allowed context with [references/mode-selection.md](references/mode-selection.md).
-2. Dispatch fresh reviewer subagents in parallel with the prompt in [references/reviewer-prompt.md](references/reviewer-prompt.md). Cover the axes in [references/review-axes.md](references/review-axes.md).
-3. Dispatch fresh validator subagents with the prompt in [references/validator-prompt.md](references/validator-prompt.md). Discard anything unconfirmed.
-4. Produce the final report exactly as defined in [references/report-format.md](references/report-format.md). Use only `approve`, `approve-with-comments`, `request-changes`, or `needs-clarification`.
-5. After the report, for a real PR only, optionally post inline comments with [references/comment-template.md](references/comment-template.md). Default to validated blocking findings only.
-
-## Rules
-
-- ALWAYS use a severity-first model: `critical`, `high`, `medium`, `low`, `nitpick`, `question`.
-- ALWAYS report only validated findings or validated missing-context questions with concrete evidence and exact `file:line` refs when code is involved.
-- DO keep findings issue-focused. DO NOT add a positive-notes section.
-- DO NOT keep style nits, speculative risks, weak evidence, pre-existing issues, or linter-catch comments.
-- DO treat blocking recommendations as requiring material production, security, UX, or maintenance risk.
-- DO treat blocking findings as the validated `critical` and `high` findings that would materially harm code health or create unacceptable production, security, UX, or maintenance risk if shipped.
-- DO NOT post unvalidated findings.
-
-## References
-
-- [references/mode-selection.md](references/mode-selection.md) - Scope parsing and allowed context.
-- [references/review-axes.md](references/review-axes.md) - Parallel reviewer-pass contracts.
-- [references/reviewer-prompt.md](references/reviewer-prompt.md) - Prompt template for one reviewer pass.
-- [references/issue-schema.md](references/issue-schema.md) - Candidate finding and question schema.
-- [references/validator-prompt.md](references/validator-prompt.md) - Prompt template for one validator pass.
-- [references/validation-rubric.md](references/validation-rubric.md) - Separate disprove-first validator rules.
-- [references/report-format.md](references/report-format.md) - Exact final report shape and decision rules.
-- [references/comment-template.md](references/comment-template.md) - Post-report inline comment format.
diff --git a/additional/skills/code-review/references/comment-template.md b/additional/skills/code-review/references/comment-template.md
deleted file mode 100644
index ec5cf66..0000000
--- a/additional/skills/code-review/references/comment-template.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Inline Comment Template
-
-Use this reference when posting validated inline PR comments after the report is shown.
-
-Default posting scope is blocking findings only unless the user explicitly widens it.
-
-## Template
-
-```markdown
-[<severity>] <short issue title>
-
-This is a real issue because <objective impact>. <Short evidence-backed why-it-matters sentence>.
-
-Validated evidence:
-
-- Code: https://github.com/<owner>/<repo>/blob/<full_sha>/<path>#L<start>-L<end>
-- Rule (if applicable): https://github.com/<owner>/<repo>/blob/<full_sha>/<rule_path>#L<start>-L<end>
-- Precedent (if applicable): https://github.com/<owner>/<repo>/blob/<full_sha>/<precedent_path>#L<start>-L<end>
-- Intent (if applicable): PR description or linked artefact reference
-```
-
-## Rules
-
-- ALWAYS use full commit SHA in all links.
-- ALWAYS prefix title with the validated severity.
-- ALWAYS include `Code` evidence.
-- DO include `Rule` evidence for `rule-violation` and `skill-contract-violation`.
-- DO include `Precedent` evidence for `consistency-drift` and any precedent-backed finding.
-- DO name the principle in the prose for principle-backed findings and cite the changed code link.
-- DO keep comments concise, factual, and non-speculative.
-- DO post only findings that survived the validator pass and are in the user-approved posting scope.
-- DO default posting scope to blocking findings only unless the user explicitly widens it.
-- DO NOT post duplicate comments for the same dedupe key.
diff --git a/additional/skills/code-review/references/mode-selection.md b/additional/skills/code-review/references/mode-selection.md
deleted file mode 100644
index 11e2b72..0000000
--- a/additional/skills/code-review/references/mode-selection.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Mode Selection
-
-Use this reference when resolving review scope.
-
-## Accepted forms
-
-- `#<pr-number>`
-- `uncommitted`
-- `branch`
-- `branch <base-branch>`
-
-No other scope forms are supported.
-
-## PR-first scope rule
-
-- If an explicit PR reference is provided, that is the primary review scope.
-- Resolve explicit PR references with `gh pr view <number> --json number,title,body,baseRefName,headRefName,files`.
-- For explicit PR review, use GitHub PR metadata for base branch, head branch, changed files, title, body, and linked artefact discovery.
-- If the current branch has an associated PR, prefer the PR as review scope for branch review.
-- If the current branch has an associated PR, prefer the PR title, description, and explicitly linked artefacts as intent context even for local fallback review.
-- If no PR exists, fall back to the requested local mode.
-- If no PR exists, use explicit user-stated review goals when intent context is needed.
-
-## Uncommitted mode
-
-- Scope includes staged, unstaged, and untracked files.
-- Review only workspace changes, not prior commits.
-
-## Branch mode
-
-- Default base branch is `main` when the user selects the default.
-- Custom base branch is allowed and must be validated.
-- Use merge-base diff: `<base>...HEAD`.
-
-## Validation checks
-
-- Confirm explicit PR references match `#<number>`.
-- Confirm branch exists locally or as `origin/<base>`.
-- If PR lookup fails, ask one corrective follow-up instead of guessing another PR.
-- If base is missing or invalid, ask one corrective follow-up.
-- If mode is missing, ask the user to choose PR review, `branch`, or `uncommitted`.
-- If the resolved scope has no reviewable file changes, still return the standard review report and state that the scope was empty.
-
-## Rules
-
-- DO accept only the documented mode forms.
-- ALWAYS preserve explicit PR scope before branch or uncommitted fallback.
diff --git a/assets/propulsion.png b/assets/propulsion_icon.png
similarity index 100%
rename from assets/propulsion.png
rename to assets/propulsion_icon.png
diff --git a/assets/propulsion2.png b/assets/propulsion_icon_square.png
similarity index 100%
rename from assets/propulsion2.png
rename to assets/propulsion_icon_square.png
diff --git a/bun.lock b/bun.lock
index 164d1c4..24e4053 100644
--- a/bun.lock
+++ b/bun.lock
@@ -6,7 +6,7 @@
"name": "propulsion",
"devDependencies": {
"oxfmt": "^0.44.0",
- "oxlint": "^1.59.0",
+ "oxlint": "^1.62.0",
"oxlint-tsgolint": "^0.20.0",
},
},
diff --git a/docs/propulsion/skill-authoring.md b/docs/propulsion/skill-authoring.md
deleted file mode 100644
index ffd8992..0000000
--- a/docs/propulsion/skill-authoring.md
+++ /dev/null
@@ -1,218 +0,0 @@
-# Propulsion Skill Authoring
-
-Use this document when creating or updating any Propulsion skill.
-
-## Goal
-
-Write skills that are explicit, strict, low-token, and hard to misread.
-
-Propulsion skills are workflow contracts. Nothing important should be implied. State the exact prerequisite, exact artifact, exact stop condition, exact completion gate, and exact next skill by name.
-
-## Core Rules
-
-- Use exact supported skill names in backticks: `propulsion-workflow`, `exploration`, `planning`, `execution`, `tdd`, `debugging`.
-- State every stage boundary explicitly. Never imply what should happen next.
-- All bug work enters through `exploration`, reaches `planning` from an approved `prd.md`, and hands off to `debugging` after planning.
-- `execution` owns feature implementation only. `debugging` owns bug diagnosis, bug-fix orchestration, review feedback loops, and closure.
-- When authoring bug-work contracts, require one living `docs/propulsion/.../debug.md` artifact that debugging creates or resumes on entry and keeps through closure.
-- Put critical gates in `SKILL.md`. Do not hide them only in `references/`.
-- Prefer hard commands over soft guidance: `MUST`, `DO NOT`, `NEVER`, `ONLY`, `STOP`, `ALL`.
-- Keep sentences short, imperative, and binary.
-- Use subagents explicitly when the workflow depends on them.
-- State what to do when prerequisites are missing. Usually: `STOP` and route to another skill by exact name.
-- State what artifact must exist, where it lives, and whether explicit user approval or a visible user-facing transition prompt is required.
-- Add a completion checklist. Do not let the skill exit without it.
-- Start each major section with its standard intro line.
-- Move explanation, examples, and long formats into `references/`.
-
-## Tone
-
-- Lead with imperatives.
-- Prefer one instruction per line.
-- Use CAPS only for control words.
-- Avoid filler, motivation, and commentary.
-- Avoid hedging like `prefer`, `usually`, `maybe`, unless the choice is genuinely optional.
-- Avoid vague language like `continue if needed`, `consider`, `handle appropriately`, `similar to`, `etc.`.
-
-## Required Shape
-
-Every Propulsion `SKILL.md` except `propulsion-workflow` MUST use this structure.
-
-`propulsion-workflow` is the only exception. It is an entry-only contract, not a standard stage skill.
-
-```md
-# Skill Name
-
-One-line mission.
-
-## Prerequisites
-
-ALL prerequisites MUST be true before following this skill.
-
-- Requirement 1
-- Requirement 2
-
-If any prerequisite are false, STOP. Load `other-skill`.
-
-## Instructions
-
-Follow these steps IN ORDER. Do NOT skip steps.
-
-1. Step 1.
-2. Step 2.
-3. Step 3.
-
-## Rules
-
-These rules are MANDATORY.
-
-- MUST ...
-- DO NOT ...
-- NEVER ...
-- ONLY ...
-
-## Completion Gate
-
-Do NOT leave this skill until ALL items are complete.
-
-- [ ] Outcome 1
-- [ ] Outcome 2
-- [ ] Outcome 3
-
-## Next Skill
-
-Once the completion gate is fully checked:
-
-- If condition A is true, load `next-skill`.
-- If condition B is true, load `different-skill`.
-
-## References
-
-Use these references when you need detail.
-
-- [references/file.md](references/file.md) - Why it exists.
-```
-
-## Section Contract
-
-Use the same section meaning every time.
-
-### Prerequisites
-
-Use this section to define the legal entry point.
-
-Standard intro line:
-
-- `ALL prerequisites MUST be true before following this skill.`
-
-- Name the prior skill if there is one.
-- Name the required artifact if there is one.
-- Name the required approval if there is one.
-- Say what to do if anything is missing.
-
-Good:
-
-- Approved `docs/propulsion/.../prd.md` exists.
-- `exploration` has completed.
-- If the PRD is missing or unapproved, STOP. Load `exploration`.
-
-### Instructions
-
-Use this section for the ordered workflow only.
-
-Standard intro line:
-
-- `Follow these steps IN ORDER. Do NOT skip steps.`
-
-- Put steps in strict sequence.
-- Put loops in plain language: `Repeat until ...`.
-- Put review and re-review loops here, not only in references.
-- If a step uses a reference file, name it inline.
-
-### Rules
-
-Use this section for non-negotiable constraints.
-
-Standard intro line:
-
-- `These rules are MANDATORY.`
-
-- Ban stage skipping.
-- Ban guessing.
-- Ban hidden transitions.
-- Ban artifact-free handoffs.
-- Ban self-approval where a fresh subagent or human approval is required.
-
-### Completion Gate
-
-Use this section as the exit test.
-
-Standard intro line:
-
-- `Do NOT leave this skill until ALL items are complete.`
-
-- Every checkbox should be observable.
-- Include artifact creation.
-- Include required approval.
-- Include verification or review if required.
-- If a checkbox is not checkable, rewrite it.
-
-### Next Skill
-
-Use exact skill names. Do not imply transitions.
-
-Standard intro line:
-
-- `Once the completion gate is fully checked:`
-
-Good:
-
-- If `prd.md` is approved, load `planning`.
-- If plan review finds missing product intent, load `exploration`.
-- If implementation review returns findings during phase execution, keep the loop inside `execution` and send the findings back to the active implementer context.
-
-Bad:
-
-- Move to the next stage.
-- Continue the workflow.
-- Review if needed.
-
-### References
-
-Use this section as the exhaustive reference list for the skill.
-
-Standard intro line:
-
-- `Use these references when you need detail.`
-
-## References Rules
-
-Use `references/` for detail, not for gates.
-
-- Put templates, formats, examples, and deeper heuristics in `references/`.
-- Mention critical references inside the ordered instructions.
-- Keep references focused and single-purpose. Consolidate tiny overlapping references when one stronger reference is clearer.
-- Do not hide approval gates, stop conditions, or next-skill routing in references.
-
-## Reference Shape
-
-Use the same reference layout every time.
-
-- Start with `# Title`.
-- Follow with one line that says when to use the reference, for example `Use this reference ...` or `Use this template ...`.
-- Put the actual template, format, heuristics, or examples next.
-- End with `## Rules` and only the reference-local rules.
-- For prompt templates, keep the full prompt in a fenced block and keep dispatch-only rules after the fence.
-
-## Author Checklist
-
-Use this before finalizing a skill.
-
-- [ ] The skill names the exact legal prerequisite skill, if any.
-- [ ] The skill names the exact legal next skill, if any.
-- [ ] The skill states what artifact must exist or be written.
-- [ ] The skill states whether explicit user approval or a visible transition prompt is required.
-- [ ] The skill states what the agent must do if inputs are missing.
-- [ ] The skill uses strong explicit wording, not implied behavior.
-- [ ] The skill keeps long detail in `references/`.
-- [ ] The skill conforms to `agentic-skills`.
diff --git a/hooks/hooks.json b/hooks/hooks.json
new file mode 100644
index 0000000..1668310
--- /dev/null
+++ b/hooks/hooks.json
@@ -0,0 +1,15 @@
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "matcher": "startup|clear|compact|resume",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "./hooks/run-hook.cmd session-start"
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/hooks/run-hook.cmd b/hooks/run-hook.cmd
new file mode 100755
index 0000000..8041bfd
--- /dev/null
+++ b/hooks/run-hook.cmd
@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+
+script_name="${1:?missing hook script name}"
+script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+
+exec "$script_dir/$script_name"
diff --git a/hooks/session-start b/hooks/session-start
new file mode 100755
index 0000000..f27cd64
--- /dev/null
+++ b/hooks/session-start
@@ -0,0 +1,14 @@
+#!/bin/sh
+set -eu
+
+plugin_dir="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+PLUGIN_DIR="$plugin_dir" node <<'JS'
+const { PROPULSION_BOOTSTRAP_GUIDANCE } = require(`${process.env.PLUGIN_DIR}/lib/bootstrap-guidance.js`);
+
+process.stdout.write(JSON.stringify({
+ hookSpecificOutput: {
+ hookEventName: 'SessionStart',
+ additionalContext: PROPULSION_BOOTSTRAP_GUIDANCE,
+ },
+}));
+JS
diff --git a/index.mjs b/index.mjs
new file mode 100644
index 0000000..5f25e26
--- /dev/null
+++ b/index.mjs
@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+ getPropulsionBootstrapGuidance,
+} = require('./lib/bootstrap-guidance.js');
+
+async function PropulsionPlugin() {
+ return {
+ 'experimental.chat.messages.transform': async (_input, output) => {
+ output.messages = [
+ {
+ role: 'system',
+ content: getPropulsionBootstrapGuidance(),
+ },
+ ...(output.messages ?? []),
+ ];
+ },
+ };
+}
+
+export default { server: PropulsionPlugin };
diff --git a/lib/bootstrap-guidance.js b/lib/bootstrap-guidance.js
new file mode 100644
index 0000000..6f3f8b3
--- /dev/null
+++ b/lib/bootstrap-guidance.js
@@ -0,0 +1,32 @@
+const { readFileSync } = require('node:fs');
+const { join } = require('node:path');
+
+const PROPULSION_SKILL_PATH = join(
+ __dirname,
+ '..',
+ 'skills',
+ 'propulsion',
+ 'SKILL.md',
+);
+
+function buildPropulsionBootstrapGuidance() {
+ const propulsionSkill = readFileSync(PROPULSION_SKILL_PATH, 'utf8').trim();
+
+ return `<EXTREMELY_IMPORTANT>
+Propulsion workflow entry point: load and follow the propulsion skill when the request is software work.
+Route software work through Propulsion before downstream stages.
+
+${propulsionSkill}
+</EXTREMELY_IMPORTANT>`;
+}
+
+const PROPULSION_BOOTSTRAP_GUIDANCE = buildPropulsionBootstrapGuidance();
+
+function getPropulsionBootstrapGuidance() {
+ return PROPULSION_BOOTSTRAP_GUIDANCE;
+}
+
+module.exports = {
+ PROPULSION_BOOTSTRAP_GUIDANCE,
+ getPropulsionBootstrapGuidance,
+};
diff --git a/package.json b/package.json
index 4ea3b78..96a7c84 100644
--- a/package.json
+++ b/package.json
@@ -1,37 +1,14 @@
{
"name": "propulsion",
- "version": "0.10.0",
- "description": "Compact workflow skills for agentic coding in OpenCode.",
- "homepage": "https://github.com/moonpixels/propulsion#readme",
- "bugs": {
- "url": "https://github.com/moonpixels/propulsion/issues"
- },
- "license": "ISC",
- "repository": {
- "type": "git",
- "url": "git+https://github.com/moonpixels/propulsion.git"
- },
- "files": [
- ".opencode/package.json",
- ".opencode/plugins/propulsion.js",
- "skills",
- "additional/commands",
- "additional/skills",
- "README.md",
- "additional/README.md"
- ],
- "type": "module",
- "main": "./.opencode/plugins/propulsion.js",
- "exports": {
- ".": "./.opencode/plugins/propulsion.js"
- },
+ "version": "1.0.0",
+ "main": "./index.mjs",
+ "exports": "./index.mjs",
"scripts": {
"checks": "bun run lint && bun run format && bun run test",
"format": "oxfmt .",
"format:check": "oxfmt --check .",
"lint": "oxlint",
- "test": "bun test ./tests && bash tests/opencode/run-tests.sh",
- "test:opencode": "bash tests/opencode/run-tests.sh",
+ "test": "bun test ./tests",
"test:unit": "bun test ./tests"
},
"devDependencies": {
diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md
new file mode 100644
index 0000000..c0e0055
--- /dev/null
+++ b/skills/brainstorm/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: brainstorm
+# prettier-ignore
+description: Create an approved PRD through repo inspection and interrogation. Use when scope, UX, constraints, or success criteria are unclear, or when user needs a PRD.
+---
+
+# Brainstorm
+
+Turn vague feature, UX, API, product-scope, or requirements work into an approved PRD.
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- If an approved `docs/propulsion/.../prd.md` already exists for this work, STOP. Enter the `plan` skill.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Load `interrogate` skill to close blocking branches and reach shared understanding before PRD writing.
+2. If the request is too large, decompose it and explore only the first phase or subsystem.
+3. After all blocking branches are closed and brainstorming is complete, check for relevant non-Propulsion skills and load them before writing `prd.md`.
+4. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` using the template in [references/prd-template.md](references/prd-template.md), including resolved decisions, project facts, and constraints from `interrogate`.
+5. Compare `prd.md` against the conversation for missing decisions, facts, constraints, requested behaviours, or success criteria; update `prd.md` before approval if relevant content is missing.
+6. Ask the user to review `prd.md`; treat only explicit approval, such as "approved" or "yes, proceed", as approval before entering `plan`.
+
+## Rules
+
+These rules are MANDATORY.
+
+- MUST close every blocking branch before writing `prd.md`. Blocking branches include anything that would change scope, UX, architecture, sequencing, or success criteria.
+- BEFORE writing `prd.md`, ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY.
+- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
+- MUST keep the PRD product-facing while recording durable implementation and testing decisions.
+- ENSURE the PRD includes ALL relevant decisions, even if they seem obvious or minor.
+- You CAN create supporting documents such as `docs/propulsion/.../research.md` or `docs/propulsion/.../diagrams.md` if needed, but the PRD must include all durable decisions.
+- DO include the supporting documents as implementation inputs in the PRD, but DO NOT rely on them for durable decisions.
+- DO NOT print the PRD, or other workflow artefacts in the chat, keep them in files.
+- If you cannot write files, STOP, ask the user to switch to write mode, then continue to write the PRD.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Used `interrogate` skill to reach shared understanding and close every blocking branch.
+- [ ] `prd.md` written to `docs/propulsion/.../prd.md`.
+- [ ] `prd.md` sanity-checked against the conversation and updated if relevant content was missing.
+- [ ] User has explicitly approved `prd.md` after self-review.
+
+## Next Steps
+
+Once the completion gate is fully checked:
+
+- If `prd.md` is approved, enter the `plan` skill.
+
+## References
+
+Use these references when you need detail.
+
+- [references/prd-template.md](references/prd-template.md) - PRD shape and output path.
diff --git a/skills/exploration/references/prd-template.md b/skills/brainstorm/references/prd-template.md
similarity index 93%
rename from skills/exploration/references/prd-template.md
rename to skills/brainstorm/references/prd-template.md
index 9ce7eea..03d1fc0 100644
--- a/skills/exploration/references/prd-template.md
+++ b/skills/brainstorm/references/prd-template.md
@@ -33,11 +33,11 @@ Describe the proposed behaviour end-to-end from the user's perspective.
- Durable module or boundary decisions
- Data shape or API contract decisions
-- Interaction rules that planning should not re-litigate
+- Interaction rules that the `plan` skill should not re-litigate
## Testing Decisions
-- What public behavior matters
+- What public behaviour matters
- Which modules or seams deserve tests
- Prior art worth copying from the repo
diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md
new file mode 100644
index 0000000..6a49c5b
--- /dev/null
+++ b/skills/commit/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: commit
+description: Create one safe local git commit from current changes. Use when asked to commit, save changes, or make a local checkpoint.
+---
+
+# Commit
+
+Create exactly one local git commit from safe current changes and report the result.
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- The current directory is inside a git repository with a writable index.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Inspect current state with `git status --short`, `git diff HEAD`, and `git branch --show-current`.
+2. Stage all local changes with `git add -A`, including untracked files.
+3. Unstage every staged secret-like file matching [references/workflow.md](references/workflow.md).
+4. Check staged changes after exclusions. If none remain, stop and output exactly `No changes to commit.`
+5. Generate a one-line imperative commit subject from the staged diff.
+6. Create exactly one local commit with that subject.
+7. Run `git status --short` before the final response.
+8. Report the result using the exact success format in [references/workflow.md](references/workflow.md).
+
+## Rules
+
+These rules are MANDATORY.
+
+- MUST create exactly one local commit when committable changes remain after exclusions.
+- MUST stage with `git add -A` before applying exclusions.
+- MUST unstage secret-like files before committing when they are staged.
+- MUST stop with exactly `No changes to commit.` when exclusions leave no committable changes.
+- NEVER commit secret-like files.
+- NEVER push, open pull requests, amend, reset, force, or run destructive git commands unless user explicitly instructs.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] `git add -A` was run.
+- [ ] Secret-like staged files were unstaged or none were present.
+- [ ] Exactly one local commit was created, or `No changes to commit.` was returned.
+- [ ] No push, pull request, amend, reset, force, or destructive git command was run.
+- [ ] Final output matches the required contract.
+
+## References
+
+Use these references when you need detail.
+
+- [references/workflow.md](references/workflow.md) - Secret-like exclusion patterns, commit message rules, and output contract.
diff --git a/skills/commit/references/workflow.md b/skills/commit/references/workflow.md
new file mode 100644
index 0000000..34cdc77
--- /dev/null
+++ b/skills/commit/references/workflow.md
@@ -0,0 +1,51 @@
+# Commit Workflow Reference
+
+## Inputs
+
+- Current git status: `git status --short`
+- Current git diff, staged and unstaged: `git diff HEAD`
+- Current branch: `git branch --show-current`
+
+## Secret-Like Exclusions
+
+Never commit likely secret files. Always unstage staged files matching these patterns before committing:
+
+- `.env`
+- `.env.*`
+- `*.pem`
+- `*.key`
+- `*.p12`
+- `*.pfx`
+- `credentials.json`
+- `*credentials*`
+- `*secret*`
+- `*token*`
+- `.ssh/*`
+
+## Commit Message
+
+Use a normal imperative commit subject with this format:
+
+- one line only
+- short descriptive subject line
+- imperative mood
+- normal natural wording
+- no trailing punctuation
+
+## No Committable Changes Output
+
+If no staged changes remain after exclusions, stop and output exactly:
+
+```md
+No changes to commit.
+```
+
+## Success Output
+
+Run `git status --short` before producing the final response. When the commit succeeds, output exactly:
+
+```md
+Commit created: <hash>
+Message: <final commit message>
+Excluded secret-like files: <none|comma-separated paths>
+```
diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md
new file mode 100644
index 0000000..064de92
--- /dev/null
+++ b/skills/debug/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: debug
+# prettier-ignore
+description: Handle concrete bug reports through direct intake, reproduce, diagnose, TDD-fix, verify, reset, and escalate loops. Use when failures need repair.
+---
+
+# Debug
+
+Use when a concrete failure or bug report needs diagnosis and repair.
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- The work is a bug, regression, crash, incorrect output, flaky behaviour, or other concrete failure.
+- If the work is feature-shaped or expected behaviour is intentionally being designed, STOP. Load `brainstorm`.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Create or resume `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` using [references/debug-template.md](references/debug-template.md).
+2. Load `interrogate` skill for missing user-answerable intake: report provenance, expected behaviour, actual behaviour, impact, environment, reproduction, and questions answered.
+3. Record intake answers and resolved decisions from `interrogate` in `debug.md`; if expected behaviour is unknowable, stay in `debug` and ask or block.
+4. Complete targeted codebase exploration in `debug.md` before reproduction, diagnosis, or fix work: relevant files, existing tests, commands, logs, ownership, and candidate boundaries only.
+5. Reproduce, reduce, isolate, diagnose, reset, and escalate with [references/investigation-loop.md](references/investigation-loop.md).
+6. Do not allow production-code changes until `debug.md` contains a grounded diagnosis, supporting evidence, fix constraints, and one chosen fix hypothesis.
+7. Start a fresh bug-worker subagent with [references/bug-worker-prompt.md](references/bug-worker-prompt.md), then review with [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md).
+8. If review rejects the fix, send findings back with [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md). Repeat until approved, reset when evidence contradicts the diagnosis, or reassess architecture and patterns before escalating after 3 failed fix loops.
+9. If the fix is verified and approved, record closure in `debug.md` and finish.
+
+## Rules
+
+These rules are MANDATORY.
+
+- MUST keep `debug.md` current from direct entry or resumed entry through closure.
+- MUST complete intake for expected behaviour, actual behaviour, impact, environment, and reproduction before broad code inspection or fix work.
+- MUST record `interrogate` intake answers and resolved decisions in `debug.md`.
+- MUST record targeted codebase exploration before reproduction, diagnosis, or fix work.
+- MUST stabilise reproduction, reduce the failing case, and isolate the first bad boundary or divergence before choosing a fix.
+- NEVER edit production code in the main `debug` stage.
+- EVERY fix attempt MUST start with a failing regression test and target one fix hypothesis.
+- MUST record each failed hypothesis, diagnostic edit, fix attempt, review outcome, reset, escalation, and closure in `debug.md`.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] `debug.md` exists at `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` and was created or resumed on entry.
+- [ ] Intake, `interrogate` answers and resolved decisions, targeted codebase exploration, reproduction, reduction, evidence, ranked hypotheses, experiments, diagnosis gate, fix attempts, review outcomes, verification, and closure are recorded in `debug.md`.
+- [ ] The bug is either closed with verified evidence or escalated after architecture and pattern reassessment following 3 failed fix loops.
+
+## References
+
+Use these references when you need detail.
+
+- [references/debug-template.md](references/debug-template.md) - Living `debug.md` template for the full bug dossier.
+- [references/investigation-loop.md](references/investigation-loop.md) - Core bug loop for reproduce, reduce, isolate, diagnose, reset, and escalate.
+- [references/bug-worker-prompt.md](references/bug-worker-prompt.md) - Prompt template for one diagnosis-gated TDD fix attempt.
+- [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md) - Prompt template for independent review of one bug fix attempt.
+- [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md) - Prompt template for feeding review findings back into the active bug fix attempt.
diff --git a/skills/debugging/references/bug-feedback-prompt.md b/skills/debug/references/bug-feedback-prompt.md
similarity index 82%
rename from skills/debugging/references/bug-feedback-prompt.md
rename to skills/debug/references/bug-feedback-prompt.md
index 72f5a5a..1f77357 100644
--- a/skills/debugging/references/bug-feedback-prompt.md
+++ b/skills/debug/references/bug-feedback-prompt.md
@@ -1,6 +1,6 @@
# Bug Feedback Prompt Template
-Use this template when returning reviewer findings to the active implementer during a bug-fix loop in `debugging`.
+Use this template when returning reviewer findings to the active bug-worker during a bug-fix loop in `debug`.
````markdown
**You are a subagent completing work in the Propulsion workflow.**
@@ -55,16 +55,18 @@ Use this exact format for your output.
- <finding title>
- Classification: <valid | invalid | unclear>
- Resolution: <fixed | rejected with evidence | escalated>
- - Evidence: <brief proof from code, diff, checks, behavior, or missing context>
+ - Evidence: <brief proof from code, diff, checks, behaviour, or missing context>
```
## Rules
These rules are MANDATORY.
+- Preserve the diagnosis reset and one-hypothesis discipline.
- Triage every finding before changing code.
- Do not continue coding once the diagnosis is contradicted.
- Preserve the one-hypothesis, one-fix-loop discipline.
-- Update `debug.md` before handing control back to `debugging`.
+- Do not start a second fix hypothesis inside feedback handling; if the chosen fix hypothesis fails, update `debug.md` and reset back to diagnosis.
+- Update `debug.md` before handing control back to `debug`.
- Follow the output format EXACTLY as defined above.
````
diff --git a/skills/debugging/references/bug-reviewer-prompt.md b/skills/debug/references/bug-reviewer-prompt.md
similarity index 63%
rename from skills/debugging/references/bug-reviewer-prompt.md
rename to skills/debug/references/bug-reviewer-prompt.md
index 3a91a17..43e34d9 100644
--- a/skills/debugging/references/bug-reviewer-prompt.md
+++ b/skills/debug/references/bug-reviewer-prompt.md
@@ -1,26 +1,26 @@
# Bug Reviewer Prompt Template
-Use this template when dispatching a fresh reviewer subagent for one bug-fix loop in `debugging`.
+Use this template when starting a fresh bug-reviewer subagent for one bug-fix loop in `debug`.
````markdown
**You are a subagent completing work in the Propulsion workflow.**
-You are an implementation reviewer for one bug-fix attempt under the `debugging` skill.
+You are an implementation reviewer for one bug-fix attempt under the `debug` skill.
## Inputs
-- **Plan location**: `<docs/propulsion/.../plan.md>`
- **Debug artifact**: `<docs/propulsion/.../debug.md>`
## Implementation Report
-This is the full self-review implementation report submitted by the implementer. **Do not trust it blindly, be sceptical and verify all claims yourself.**
+This is the full self-review implementation report submitted by the bug-worker. **Do not trust it blindly, be sceptical and verify all claims yourself.**
-<Copy and paste the full implementation report, excluding the title, from the implementer here>
+<Copy and paste the full implementation report, excluding the title, from the bug-worker here>
## Review Focus
- Confirm the diagnosis gate was satisfied before any production-code change.
+- Reject if any required diagnosis evidence is missing: exact symptom, reduced reproduction or flaky classification, full error reading / error-reading conclusion, recent-change conclusion, applicable working example or explicit N/A, boundary tracing, first bad boundary or divergence / first-bad-divergence, fix constraints, chosen fix hypothesis, fail-then-pass regression proof, or reset evidence from prior failed loops.
- Confirm the regression-test-first requirement was followed.
- Confirm the fix matches the chosen fix hypothesis and fix constraints in `debug.md`.
- Confirm verification is sufficient for the reported bug behaviour.
@@ -32,10 +32,10 @@ Follow these steps IN ORDER. Do NOT skip steps.
1. Read the current `debug.md` and implementation report in full.
2. Inspect the real code and diff, not just the report.
-3. Verify the regression test failed first, then passed after the fix.
+3. Verify the regression test failed first, then passed after the fix; `debug.md` must show the failing result before fix and passing result after fix.
4. Verify the change stays within the chosen fix hypothesis and does not hide unexplained evidence.
5. Return approval only if the diagnosis gate, regression-test-first requirement, diagnosis status, and verification all hold.
-6. If anything fails, reject the attempt and state whether `debugging` must reset back to diagnosis.
+6. If anything fails, reject the attempt and state whether `debug` must reset back to diagnosis.
## Output
@@ -49,16 +49,18 @@ Use this exact format for your output.
**Diagnosis Status**
- <still holds | contradicted | unclear>
- - Evidence: <brief proof from `debug.md`, diff, checks, behavior, or missing verification>
+ - Evidence: <brief proof from `debug.md`, diff, checks, behaviour, or missing verification>
**Verification Status**
- Regression-test-first requirement: <met | not met | unclear>
- - Evidence: <brief proof from code, diff, checks, behavior, or missing verification>
+ - Evidence: <brief proof from code, diff, checks, behaviour, or missing verification>
+- Failing result before fix and passing result after fix: <met | not met | unclear>
+ - Evidence: <brief proof from `debug.md`, test output, checks, behaviour, or missing verification>
- Chosen fix hypothesis respected: <met | not met | unclear>
- - Evidence: <brief proof from code, diff, checks, behavior, or missing verification>
-- Verification sufficient for bug behavior: <met | not met | unclear>
- - Evidence: <brief proof from code, diff, checks, behavior, or missing verification>
+ - Evidence: <brief proof from code, diff, checks, behaviour, or missing verification>
+- Verification sufficient for bug behaviour: <met | not met | unclear>
+ - Evidence: <brief proof from code, diff, checks, behaviour, or missing verification>
<if findings, include this section>
@@ -83,9 +85,10 @@ Use this exact format for your output.
These rules are MANDATORY.
- Treat the diagnosis gate as required, not advisory.
-- ALWAYS check for non-Propulsion skills that are relevant to this task and load them IMMEDIATELY using the skill tool.
+- ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY.
- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
- Reject speculative or symptom-only fixes.
+- Reject missing root-cause evidence, missing fail-then-pass proof, changes outside the chosen fix hypothesis, or permanent code changes made outside the bug-worker subagent.
- Call out missing verification or contradictory evidence explicitly.
- MUST return exactly one `Status:` line with either `approved` or `rejected`.
- If `Status: rejected`, MUST include at least one finding.
diff --git a/skills/debugging/references/bug-implementer-prompt.md b/skills/debug/references/bug-worker-prompt.md
similarity index 58%
rename from skills/debugging/references/bug-implementer-prompt.md
rename to skills/debug/references/bug-worker-prompt.md
index 2b923e8..fe00be5 100644
--- a/skills/debugging/references/bug-implementer-prompt.md
+++ b/skills/debug/references/bug-worker-prompt.md
@@ -1,15 +1,14 @@
-# Bug Implementer Prompt Template
+# Bug Worker Prompt Template
-Use this template when dispatching a fresh implementer subagent for one bug-fix loop in `debugging`.
+Use this template when starting a fresh bug-worker subagent for one bug-fix loop in `debug`.
````markdown
**You are a subagent completing work in the Propulsion workflow.**
-You are a senior software engineer implementing one bug-fix attempt under the `debugging` skill.
+You are a senior software engineer implementing one bug-fix attempt under the `debug` skill.
## Bug Context
-- **Plan location**: `<docs/propulsion/.../plan.md>`
- **Debug artifact**: `<docs/propulsion/.../debug.md>`
- **Chosen fix hypothesis**: `<copy the current fix hypothesis verbatim from debug.md>`
- **Fix constraints**: `<copy the current fix constraints from debug.md>`
@@ -19,11 +18,12 @@ You are a senior software engineer implementing one bug-fix attempt under the `d
Follow these steps IN ORDER. Do NOT skip steps.
1. Review the bug context and ask questions if the diagnosis gate, scope, or repo state is unclear. Do not guess.
-2. If the diagnosis gate is not satisfied, STOP and report that `debugging` must return to diagnosis before a fix attempt.
-3. Load the `tdd` skill NOW and follow the guidance.
-4. Implement one bug-fix attempt for the chosen fix hypothesis.
-5. Update `debug.md` with the regression test, fix attempt, verification result, and any contradictory evidence.
-6. Return an implementation report in the exact format defined below.
+2. Verify the full diagnosis gate evidence checklist in `debug.md`: exact symptom, reduced reproduction or flaky classification, full error reading, recent-change conclusion, applicable working example or explicit N/A, boundary tracing, first bad boundary or divergence, fix constraints, chosen fix hypothesis, and reset evidence from prior loops if any.
+3. If the diagnosis gate is not satisfied, STOP and report that `debug` must return to diagnosis before a fix attempt.
+4. Load the `tdd` skill NOW and follow it.
+5. Implement one bug-fix attempt for the chosen fix hypothesis.
+6. Update `debug.md` with the regression test, fix attempt, verification result, and any contradictory evidence.
+7. Return an implementation report in the exact format defined below.
## Output
@@ -58,9 +58,10 @@ Use this exact format for your output.
These rules are MANDATORY.
- Load the `tdd` skill NOW.
-- ALWAYS check for non-Propulsion skills that are relevant to this task and load them IMMEDIATELY using the skill tool.
+- ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY.
- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
- NO PRODUCTION CODE before the failing regression test.
+- Only bug-worker subagents make permanent code changes; the debug controller may make temporary diagnostic edits only when they are recorded and reverted before fix handoff.
- Work only on the chosen fix hypothesis for this loop.
- Make one minimal fix attempt only.
- If evidence contradicts the diagnosis, STOP, update `debug.md`, and reset back to diagnosis.
diff --git a/skills/debug/references/debug-template.md b/skills/debug/references/debug-template.md
new file mode 100644
index 0000000..298b0ab
--- /dev/null
+++ b/skills/debug/references/debug-template.md
@@ -0,0 +1,174 @@
+# Debug Template
+
+Write a living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` artifact using this exact section order.
+
+```md
+# Debug Note: <bug>
+
+## User Report Provenance
+
+- Source: `<user message, issue, PR, alert, log, support ticket, or other origin>`
+- Reporter and timestamp: `<who reported it and when, if known>`
+- Original report excerpt: `<verbatim summary or link>`
+- Prior artifact resumed: `<debug.md path or None>`
+
+## Intake Questions Answered
+
+- Exact symptom: `<failing test, build step, crash, assertion, wrong output, or visible bad behaviour>`
+- Expected behaviour: `<what should happen; block if unknowable>`
+- Actual behaviour: `<what happens instead>`
+- Impact: `<severity, affected users, frequency, business or workflow effect>`
+- Environment: `<OS, runtime, browser, device, CI, production, tenant, dataset, versions>`
+- Reproduction: `<exact command, script, URL, manual path, or missing detail>`
+- Questions answered: `<Q/A list with the user or evidence source>`
+- Open questions or blockers: `<unknowns that prevent reproduction, expected behaviour, or diagnosis>`
+
+## Targeted Codebase Exploration
+
+- Relevant files or areas: `<small set of paths inspected and why>`
+- Existing tests or commands: `<tests, scripts, logs, traces, or smoke paths likely to reproduce or verify>`
+- Ownership and prior context: `<recent commits, related docs, issues, or maintainers if known>`
+- Likely seams or boundaries: `<public interface, subsystem handoff, config, data, timing, or environment boundary>`
+- Exploration limits: `<what was intentionally not inspected before reproduction>`
+
+## Reproduction
+
+- Status: `<deterministic | flaky | not yet stable>`
+- Exact command or path: `<single reproducing command, script, or manual flow>`
+- Expected behaviour: `<what should happen>`
+- Actual behaviour: `<what happens instead>`
+- Reduced reproduction or flaky classification: `<smallest stable repro, flaky proof, or why not yet reduced>`
+
+## Full Error Reading
+
+- Full error, stack, warning, assertion, and exit code: `<verbatim or linked complete output>`
+- First meaningful frame: `<earliest useful application, config, dependency, or boundary frame>`
+- Relevant surrounding logs or traces: `<only facts needed to understand the failure>`
+- Error-reading conclusion: `<what the full output proves and what it does not prove>`
+
+## Environment Facts
+
+- Revision / branch / artifact: `<commit, branch, build, image, or release>`
+- Runtime and platform: `<OS, runtime, dependency versions>`
+- Inputs, flags, config, and data facts: `<only facts that affect reproduction>`
+- Scope: `<local | CI | production | tenant | dataset | path>`
+
+## Recent Changes
+
+- Working tree and staged diff: `<relevant changed files or None>`
+- Recent commits or release delta: `<good/bad window, candidate commits, or None>`
+- Dependencies, config, environment, CI, and runtime drift: `<changes found or None>`
+- Recent-change conclusion: `<which changes remain plausible and why>`
+
+## Reduction And Isolation
+
+- Smallest failing case found: `<reduced test, request, input, or path>`
+- What was removed or controlled: `<fixtures, services, flags, timing, data>`
+- Good / bad comparison points: `<known-good input, env, trace, commit, or output>`
+
+## Working Examples
+
+- Working example or reference implementation: `<passing test, sample, prior release, adjacent feature, or N/A>`
+- Broken versus working comparison: `<key input, output, state, config, trace, or behaviour differences>`
+- First observed divergence: `<earliest difference between working and broken paths>`
+
+## Diagnostic Edits
+
+- Temporary diagnostic edits made: `<file, purpose, and exact observation, or None>`
+- Revert status: `<reverted before fix handoff | not applicable>`
+- Diagnostic edit outcome: `<what was proven, disproven, or left unclear>`
+
+## Boundary Tracing
+
+- Boundary map: `<components, layers, services, files, or processes crossed by the failing path>`
+- Ingress observations: `<input, request, event, props, state, or config entering each boundary>`
+- Egress observations: `<output, response, emitted event, mutated state, or error leaving each boundary>`
+- Config propagation: `<where config/env/flags are read, transformed, or lost>`
+- State at each component handoff: `<state snapshot or invariant at each handoff>`
+- First bad boundary or divergence: `<component, layer, handoff, state, or frame where good turns bad>`
+
+## Evidence
+
+- E1. `<command, log, trace, dump, screenshot, diagnostic edit, or debugger observation>`
+- E2. `<next evidence item>`
+- E3. `<next evidence item>`
+
+## Hypotheses And Experiments
+
+- H1. `<current best hypothesis>`
+ - Why plausible: `<evidence that points here>`
+ - Strongest alternative: `<next best explanation>`
+ - Experiment: `<single discriminating step>`
+ - Expected result: `<what would support H1>`
+ - Actual result: `<observed outcome>`
+ - Falsifier: `<what would disprove H1>`
+ - Conclusion: `<supported | disproved | unclear>`
+- H2. `<alternative or eliminated hypothesis>`
+ - Why plausible: `<brief reason>`
+ - Experiment: `<single discriminating step>`
+ - Actual result: `<observed outcome>`
+ - Falsifier: `<what would disprove H2>`
+ - Conclusion: `<supported | disproved | unclear>`
+- Experiment outcomes: `<summary of supported, disproved, and unclear hypotheses>`
+
+## Diagnosis Gate
+
+- First bad state or divergence: `<earliest state proven wrong>`
+- Root cause statement: `<specific condition>` caused `<failure>` because `<mechanism>`
+- Falsifier: `<result that would prove the diagnosis wrong>`
+- Fix constraints: `<behaviour, compatibility, observability, and invariants the fix must preserve>`
+- Gate status: `<open | grounded>`
+
+## Fix Hypothesis
+
+- Chosen fix hypothesis: `<single change expected to remove the root cause; leave unset until gate is grounded>`
+- Why this fix follows from the diagnosis: `<tie back to evidence and first bad state>`
+- Loop number: `<1 | 2 | 3>`
+
+## Regression Test
+
+- Test location: `<path>`
+- behaviour under test: `<public interface or stable seam>`
+- Failing result before fix: `<proof the regression exists>`
+- Passing result after fix: `<proof the behaviour now holds>`
+
+## Fix Attempts
+
+- Attempt 1: `<summary>`
+ - Files changed: `<paths>`
+ - Verification: `<checks run and result>`
+ - Review result: `<approved | rejected>`
+ - Outcome: `<closed | reset to diagnosis>`
+- Attempt 2: `<summary or N/A>`
+
+## Verification
+
+- Targeted checks: `<commands and outcomes>`
+- Wider regression checks: `<commands and outcomes>`
+- Remaining unexplained evidence: `<None or list>`
+
+## Architecture And Pattern Reassessment
+
+- Trigger: `<after 3 failed fix loops | not reached>`
+- Failed loop summary: `<attempts, hypotheses, review outcomes, and reset reasons>`
+- Architecture or pattern reassessment: `<ownership, boundaries, abstractions, data flow, or workflow assumptions reconsidered>`
+- Next direction before escalation: `<new diagnosis direction, architecture concern to investigate, or reason escalation is required>`
+
+## Closure
+
+- Final status: `<fixed | escalated | still diagnosing>`
+- User-visible resolution: `<what changed for the user>`
+- Closure evidence: `<verified fix, reason for escalation, or reason diagnosis remains blocked>`
+- Follow-ups: `<cleanup, hardening, or None>`
+```
+
+## Rules
+
+- `debug.md` starts or resumes in `debug` and stays the single living bug artifact for later loops.
+- Capture user report provenance, exact symptom, expected behaviour, actual behaviour, environment facts, full error reading, recent changes, reduced reproduction or flaky classification, working examples, diagnostic edits, boundary tracing, first bad boundary or divergence, hypotheses, falsifiers, fix constraints, chosen fix hypothesis, experiment outcomes, fix attempts, review outcomes, and closure together in one file.
+- If expected behaviour is unknowable, keep asking or block in `debug`; do not route to fixing.
+- The diagnosis gate must be grounded before any production-code change.
+- Record failed hypotheses, diagnostic edits, failed fix loops, resets, and escalations explicitly; do not erase them.
+- After 3 failed fix loops, reassess architecture and patterns before user escalation.
+- Temporary diagnostic edits must be reverted and recorded before fix handoff.
+- Keep the artifact short, concrete, and evidence-backed.
diff --git a/skills/debugging/references/investigation-loop.md b/skills/debug/references/investigation-loop.md
similarity index 60%
rename from skills/debugging/references/investigation-loop.md
rename to skills/debug/references/investigation-loop.md
index b932949..7e0f931 100644
--- a/skills/debugging/references/investigation-loop.md
+++ b/skills/debug/references/investigation-loop.md
@@ -1,44 +1,62 @@
# Investigation Loop
-Use this reference to keep `debugging` aligned with systematic, evidence-first bug resolution.
+Use this reference to keep `debug` aligned with systematic, evidence-first bug resolution.
+
+## Iron Law
+
+No fixes before grounded root-cause investigation. Do not choose a fix hypothesis, dispatch production-code work, or edit production code until the evidence explains the earliest bad state or divergence. Temporary diagnostic edits are allowed only when recorded in `debug.md`, used for investigation, and reverted before fix handoff.
Work the loop in this order and keep `debug.md` current after each step.
1. Reproduce and stabilise.
- Capture the exact symptom, failing assertion, wrong output, or visible bad behaviour.
+- Read the failure fully: full error, stack, warning, assertion, logs, exit code, and first meaningful frame before summarising.
- Freeze the environment facts that matter: revision, runtime, flags, config, inputs, time, locale, dataset, and scope.
- Reduce moving parts until one command, script, or exact manual path reproduces the issue, or classify it explicitly as flaky.
-2. Reduce the case.
+2. Scan recent changes.
+
+- Check recent changes before broad code reading: working tree diff, staged diff, recent commits, dependencies, config changes, environment changes, CI changes, and runtime drift.
+- Record the smallest credible good/bad window when one exists.
+- Treat drift as evidence, not a diagnosis, until tied to the reproduced symptom.
+
+3. Reduce the case.
- Minimise setup, fixtures, services, flags, and data while preserving the same symptom.
- Prefer the smallest practical failing case. This follows the delta-debugging idea: remove variables until the bug survives in less space.
- If the symptom changes, record that you changed the problem.
-3. Isolate the first bad boundary.
+4. Compare working examples.
+
+- When applicable, compare against a working example, reference implementation, adjacent passing test, prior release, documented sample, or known-good trace.
+- Record the first meaningful divergence between broken and working paths.
+- If no useful working example exists, record why.
+
+5. Isolate the first bad boundary.
- Compare broken versus working inputs, environments, traces, or outputs.
- Find the first component, layer, handoff, or state transition where the signal changes from good to bad.
+- Trace boundary data explicitly: ingress, egress, config propagation, and state at each component handoff.
- If a good/bad history window exists, isolate it before broad code reading. Diff debugging beats guessing.
-4. Diagnose with one ranked hypothesis at a time.
+6. Diagnose with one ranked hypothesis at a time.
- Keep a short list: current best hypothesis, strongest alternative, and unexplained evidence.
- Run one discriminating experiment at a time and record the expected result first.
- Trace backward from the late symptom to the earliest explainable bad state or divergence.
- Use existing logs, traces, dumps, breakpoints, logpoints, watchpoints, and debugger-led inspection before mutating logic.
-5. Gate the fix.
+7. Gate the fix.
- Do not choose a fix until the diagnosis explains the first bad state or divergence, not just the late symptom.
- Record one chosen fix hypothesis, the falsifier, and fix constraints in `debug.md`.
- If the evidence no longer fits, reset the diagnosis instead of pushing through.
-6. Verify the fix loop result.
+8. Verify the fix loop result.
- If a dispatched fix attempt fails verification or contradicts the diagnosis, return to step 1 or 2 with the new evidence.
-- After 3 failed fix loops, escalate to the user with the failed loops summarised in `debug.md`.
+- After 3 failed fix loops, reassess architecture and patterns before user escalation, then escalate with the failed loops and reassessment summarised in `debug.md`.
Use these narrowing moves when the failure clearly fits one:
@@ -52,8 +70,14 @@ Use these narrowing moves when the failure clearly fits one:
## Rules
+- No fixes before grounded root-cause investigation.
- Reproduce before theorising.
+- Read the full error before summarising.
+- Scan recent changes before widening the search.
- Reduce before widening the search.
- Isolate before fixing.
+- Compare against a working example or reference when applicable.
+- Trace ingress, egress, config propagation, and state at each component handoff.
- One hypothesis, one experiment, one fix at a time.
- Reset immediately when verification or evidence breaks the current model.
+- Reassess architecture and patterns after 3 failed fix loops before escalating to the user.
diff --git a/skills/debugging/SKILL.md b/skills/debugging/SKILL.md
deleted file mode 100644
index 54f223c..0000000
--- a/skills/debugging/SKILL.md
+++ /dev/null
@@ -1,78 +0,0 @@
----
-name: debugging
-# prettier-ignore
-description: Resolve planned bug work through a strict reproduce, diagnose, TDD-fix, verify, reset, and escalate loop.
----
-
-# Debugging
-
-Use when bug work is ready to resolve after `planning`.
-
-## Prerequisites
-
-ALL prerequisites MUST be true before following this skill.
-
-- If no `docs/propulsion/.../plan.md` exists for this work, STOP. Load `planning`.
-- If the plan is feature-oriented, STOP. Load `execution`.
-
-## Instructions
-
-Follow these steps IN ORDER. Do NOT skip steps.
-
-1. Create or resume `docs/propulsion/{yyyymmdd}-{feature-name}/debug.md` using the template in [references/debug-template.md](references/debug-template.md).
-2. Reproduce and stabilise the bug with [references/investigation-loop.md](references/investigation-loop.md). Record the exact symptom, environment facts, and one stable reproducing command or explicit flaky classification.
-3. Reduce and isolate the failure. Shrink the failing case, isolate the first bad boundary or first meaningful divergence, and keep a short ranked hypothesis list with one discriminating experiment at a time.
-4. Diagnose and gate the fix. Do not allow production-code changes until `debug.md` contains the grounded diagnosis, supporting evidence, fix constraints, and one chosen fix hypothesis that explains the first bad state or divergence.
-5. Dispatch a fresh implementer subagent with the prompt in [references/bug-implementer-prompt.md](references/bug-implementer-prompt.md).
-6. Wait for the implementer to finish and report back.
-7. If the implementer reports `Status: unclear` then provide additional context or clarification to the implementer.
-8. If the implementer reports `Status: blocked` then triage the blocker and resolve it.
-9. Escalate to the user if you are unable to resolve `unclear` or `blocked` statuses from `debug.md`, `plan.md`, the codebase, or the available tools.
-10. If the implementer reports `Status: done` then dispatch a fresh reviewer subagent with the prompt in [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md).
-11. If the bug-reviewer reports `Status: rejected`, send the findings back to the same implementer subagent session with the prompt in [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md).
-12. Repeat steps 6-11 until the implementer reports `Status: done` and the latest bug-reviewer reports `Status: approved`, or until the diagnosis is contradicted and must reset.
-13. If the fix attempt fails verification, contradicts the diagnosis, or introduces new unexplained behaviour, update `debug.md`, reset to step 2, and run the next loop only after the diagnosis is grounded again.
-14. If the fix is verified and approved, record closure in `debug.md` and finish. After 3 failed fix loops, STOP and escalate to the user.
-
-## Rules
-
-These rules are MANDATORY.
-
-- MUST keep `debug.md` current from entry to closure.
-- MUST stabilise reproduction before broad code inspection or fix work.
-- MUST reduce the failing case and isolate the first bad boundary or divergence before choosing a fix.
-- MUST keep a short ranked hypothesis list and run one discriminating experiment at a time.
-- NEVER edit production code in the main `debugging` stage.
-- ONLY a dispatched implementer subagent may attempt the bug fix, and only after the diagnosis gate is satisfied.
-- EVERY fix attempt MUST start with a failing regression test and target one fix hypothesis.
-- If a fix attempt fails verification, contradicts the diagnosis, or introduces new unexplained behaviour, MUST reset to diagnosis immediately.
-- MUST record each failed loop in `debug.md`, including what was tried, what failed, and what evidence changed.
-- After 3 failed fix loops, MUST escalate to the user instead of continuing blindly.
-
-## Completion Gate
-
-Do NOT leave this skill until ALL items are complete.
-
-- [ ] `debug.md` exists at `docs/propulsion/{yyyymmdd}-{feature-name}/debug.md` and was created or resumed on entry.
-- [ ] Reproduction, reduction, evidence, ranked hypotheses, experiments, and diagnosis gate are recorded in `debug.md`.
-- [ ] The first bad boundary, first divergence, or earliest explainable bad transition is grounded by evidence.
-- [ ] At least one fix hypothesis, regression test result, fix attempt result, and verification outcome are recorded in `debug.md`.
-- [ ] The bug is either closed with verified evidence or escalated after 3 failed fix loops.
-
-## Next Skill
-
-Once the completion gate is fully checked:
-
-- If the bug is fixed and verified, STOP. Tell the user the bug is fixed and ask whether they have any feedback on the fix.
-- If later evidence contradicts the current diagnosis or fix, load `debugging` and resume the same `debug.md`.
-- If the work is no longer a bug and has become behaviour-shaping product work, load `exploration`.
-
-## References
-
-Use these references when you need detail.
-
-- [references/investigation-loop.md](references/investigation-loop.md) - Core bug loop for reproduce, reduce, isolate, diagnose, reset, and escalate.
-- [references/debug-template.md](references/debug-template.md) - Living `debug.md` template for the full bug dossier.
-- [references/bug-implementer-prompt.md](references/bug-implementer-prompt.md) - Prompt template for one diagnosis-gated TDD fix attempt.
-- [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md) - Prompt template for independent review of one bug fix attempt.
-- [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md) - Prompt template for feeding review findings back into the active bug fix attempt.
diff --git a/skills/debugging/references/debug-template.md b/skills/debugging/references/debug-template.md
deleted file mode 100644
index 7eb3cfb..0000000
--- a/skills/debugging/references/debug-template.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# Debug Template
-
-Write living `docs/propulsion/{yyyymmdd}-{feature-name}/debug.md` artifact using this exact section order.
-
-```md
-# Debug Note: <bug>
-
-## Reproduction
-
-- Status: `<deterministic | flaky | not yet stable>`
-- Exact command or path: `<single reproducing command, script, or manual flow>`
-- Expected behavior: `<what should happen>`
-- Actual behavior: `<what happens instead>`
-
-## Environment Facts
-
-- Revision / branch / artifact: `<commit, branch, build, image, or release>`
-- Runtime and platform: `<OS, runtime, dependency versions>`
-- Inputs, flags, config, and data facts: `<only facts that affect reproduction>`
-- Scope: `<local | CI | production | tenant | dataset | path>`
-
-## Reduction And Isolation
-
-- Smallest failing case found: `<reduced test, request, input, or path>`
-- What was removed or controlled: `<fixtures, services, flags, timing, data>`
-- First bad boundary or divergence: `<component, layer, handoff, or state>`
-- Good / bad comparison points: `<known-good input, env, trace, commit, or output>`
-
-## Evidence
-
-- E1. `<command, log, trace, dump, screenshot, or debugger observation>`
-- E2. `<next evidence item>`
-- E3. `<next evidence item>`
-
-## Hypotheses And Experiments
-
-- H1. `<current best hypothesis>`
- - Why plausible: `<evidence that points here>`
- - Strongest alternative: `<next best explanation>`
- - Experiment: `<single discriminating step>`
- - Expected result: `<what would support H1>`
- - Actual result: `<observed outcome>`
- - Conclusion: `<supported | disproved | unclear>`
-- H2. `<alternative or eliminated hypothesis>`
- - Why plausible: `<brief reason>`
- - Experiment: `<single discriminating step>`
- - Actual result: `<observed outcome>`
- - Conclusion: `<supported | disproved | unclear>`
-
-## Diagnosis Gate
-
-- First bad state or divergence: `<earliest state proven wrong>`
-- Root cause statement: `<specific condition>` caused `<failure>` because `<mechanism>`
-- Falsifier: `<result that would prove the diagnosis wrong>`
-- Fix constraints: `<behavior and invariants the fix must preserve>`
-- Gate status: `<open | grounded>`
-
-## Fix Hypothesis
-
-- Chosen fix hypothesis: `<single change expected to remove the root cause>`
-- Why this fix follows from the diagnosis: `<tie back to evidence and first bad state>`
-- Loop number: `<1 | 2 | 3>`
-
-## Regression Test
-
-- Test location: `<path>`
-- Behavior under test: `<public interface or stable seam>`
-- Failing result before fix: `<proof the regression exists>`
-- Passing result after fix: `<proof the behavior now holds>`
-
-## Fix Attempts
-
-- Attempt 1: `<summary>`
- - Files changed: `<paths>`
- - Verification: `<checks run and result>`
- - Review result: `<approved | rejected>`
- - Outcome: `<closed | reset to diagnosis>`
-- Attempt 2: `<summary or N/A>`
-
-## Verification
-
-- Targeted checks: `<commands and outcomes>`
-- Wider regression checks: `<commands and outcomes>`
-- Remaining unexplained evidence: `<None or list>`
-
-## Closure
-
-- Final status: `<fixed | escalated | still diagnosing>`
-- User-visible resolution: `<what changed for the user>`
-- Follow-ups: `<cleanup, hardening, or None>`
-```
-
-## Rules
-
-- `debug.md` starts in `debugging` and stays the single living bug artifact for later loops.
-- Keep evidence, diagnosis, fix attempts, and closure together in one file.
-- The diagnosis gate must be grounded before any production-code change.
-- Record failed fix loops, resets, and escalations explicitly; do not erase them.
-- Keep the artifact short, concrete, and evidence-backed.
diff --git a/skills/execute/SKILL.md b/skills/execute/SKILL.md
new file mode 100644
index 0000000..7baf1fb
--- /dev/null
+++ b/skills/execute/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: execute
+# prettier-ignore
+description: Execute a feature plan through subagent implementation and review one phase at a time. Use when current `plan.md` exists and the user wants feature implementation to start.
+---
+
+# Execute
+
+Execute a feature plan one phase at a time.
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- If no `docs/propulsion/.../plan.md` exists for this work, STOP. Load `plan`.
+- If the plan is bug-oriented, STOP. Load `debug`.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Review `plan.md` to understand how each phase is scoped.
+2. Select the first incomplete phase in `plan.md` as the current phase.
+3. Start a fresh worker subagent with the prompt in [references/worker-prompt.md](references/worker-prompt.md).
+4. Wait for the worker to finish and report back.
+5. If the worker reports `Status: unclear` then provide additional context or clarification to the worker.
+6. If the worker reports `Status: blocked` then triage the blocker and resolve it.
+7. Escalate to the user if you are unable to resolve `unclear` or `blocked` statuses from context within the plan, codebase, or tools.
+8. If the worker reports `Status: done` then start a fresh implementation-reviewer subagent with the prompt in [references/reviewer-prompt.md](references/reviewer-prompt.md).
+9. If the implementation-reviewer reports `Status: rejected`, send the findings back to the same worker subagent with the prompt in [references/worker-feedback-prompt.md](references/worker-feedback-prompt.md).
+10. Repeat steps 4-9 until the worker reports `Status: done` and the latest implementation-reviewer reports `Status: approved`.
+11. Check off the current phase acceptance criteria and phase completion in `plan.md`.
+12. Repeat steps 2-11 for the next incomplete phase in `plan.md` until all phases are complete.
+13. After the last phase is complete, infer and run the final repo-wide checks from the target repository's docs, scripts, and conventions before claiming the plan complete.
+
+## Rules
+
+These rules are MANDATORY.
+
+- DO NOT implement work from the orchestrating agent; ALWAYS use a fresh worker subagent for each phase.
+- ALWAYS use a fresh implementation-reviewer subagent for each phase review.
+- DO NOT use `execute` for bug diagnosis, bug-fix orchestration, or bug-fix feedback loops; those belong to `debug`.
+- NEVER resolve `Status: unclear` or `Status: blocked` by guessing. If the information is not in the plan, codebase, or tools, escalate to the user for resolution.
+- ALWAYS update `plan.md` checkboxes after each successful implementation-review cycle.
+- ALWAYS use the prompts in the references when starting subagents and sending feedback.
+- DO NOT directly implement user feedback once the completion gate is passed; loop back to `brainstorm` instead.
+- You CAN use parallel worker subagents for different phases ONLY IF the phases are truly independent with no shared dependencies or risk of conflicts.
+- DO NOT claim completion without final repo-wide checks chosen from the target repository's docs, scripts, and conventions.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Every phase in `plan.md` has gone through a worker subagent and received `Status: done`.
+- [ ] Every phase in `plan.md` has gone through an implementation-reviewer subagent and received `Status: approved`.
+- [ ] Every phase acceptance criterion and phase completion checkbox in `plan.md` is checked off.
+- [ ] Final repo-wide checks pass.
+- [ ] Completion evidence is provided to the user.
+
+## Next Steps
+
+Once the completion gate is fully checked:
+
+- Tell the user the plan is fully executed and ask whether they have any feedback on the implementation.
+- If the user provides feedback after this completion handoff, do not implement it in `execute`; load `brainstorm` to update the PRD, then `plan` to create or update a phase, then return to `execute` for implementation.
+
+## References
+
+Use these references when you need detail.
+
+- [references/worker-prompt.md](references/worker-prompt.md) - Fresh worker subagent prompt.
+- [references/reviewer-prompt.md](references/reviewer-prompt.md) - Fresh implementation-reviewer subagent prompt.
+- [references/worker-feedback-prompt.md](references/worker-feedback-prompt.md) - Prompt for sending implementation-reviewer findings back to the worker subagent.
diff --git a/skills/execution/references/implementation-reviewer-prompt.md b/skills/execute/references/reviewer-prompt.md
similarity index 78%
rename from skills/execution/references/implementation-reviewer-prompt.md
rename to skills/execute/references/reviewer-prompt.md
index eda038a..5f35739 100644
--- a/skills/execution/references/implementation-reviewer-prompt.md
+++ b/skills/execute/references/reviewer-prompt.md
@@ -1,6 +1,6 @@
-# Implementation Reviewer Prompt Template
+# Reviewer Prompt Template
-Use this template when dispatching a fresh implementation-reviewer subagent in the `execution` skill.
+Use this template when starting a fresh reviewer subagent in the `execute` skill.
````markdown
**You are a subagent completing work in the Propulsion workflow.**
@@ -15,19 +15,19 @@ You are an implementation reviewer. Verify that work for the current phase has b
## Implementation Report
-This is the full self-review implementation report submitted by the implementer. **Do not trust it blindly, be sceptical and verify all claims yourself.**
+This is the full self-review implementation report submitted by the worker. **Do not trust it blindly, be sceptical and verify all claims yourself.**
-<Copy and paste the full implementation report, excluding the title, from the implementer here>
+<Copy and paste the full implementation report, excluding the title, from the worker here>
## Review Criteria
-| Category | What to verify |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| Phase Scope | The implementation matches the current phase goal, likely areas, and constraints without drifting into unrelated work. |
-| Acceptance Criteria | Every current-phase acceptance criterion is verified against the real implementation with explicit evidence. |
-| Correctness | The code, prompts, workflow, and behavior actually do what the phase claims, with no broken logic or contradictory text. |
-| Verification Quality | Checks run are relevant, results support the claims made, and no obvious verification gap hides a real issue. |
-| Regression Risk | The change does not introduce obvious breakage, dead steps, or workflow gaps in the surrounding execution loop. |
+| Category | What to verify |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Phase Scope | The implementation matches the current phase goal, likely areas, and constraints without drifting into unrelated work. |
+| Acceptance Criteria | Every current-phase acceptance criterion is verified against the real implementation with explicit evidence. |
+| Correctness | The code, prompts, workflow, and behaviour actually do what the phase claims, with no broken logic or contradictory text. |
+| Verification Quality | Checks run are relevant, results support the claims made, and no obvious verification gap hides a real issue. |
+| Regression Risk | The change does not introduce obvious breakage, dead steps, or workflow gaps in the surrounding execute loop. |
Flag only real issues you can support with evidence from the code, diff, prompts, plan, or verification output.
@@ -39,9 +39,9 @@ Follow these steps IN ORDER. Do NOT skip steps.
2. Review the full implementation report to understand what was implemented.
3. Inspect the real implementation directly in the repo. Read the changed files, inspect the diff, and verify any claimed checks or evidence.
4. Review every acceptance criterion one by one and decide whether it is met, not met, or unclear from the available evidence.
-5. Treat the implementer's report as an input, not as proof. If a claim is unsupported by the code, diff, or verification evidence, do not accept it.
+5. Treat the worker's report as an input, not as proof. If a claim is unsupported by the code, diff, or verification evidence, do not accept it.
6. If you find an issue, report it as a severity-ranked finding with a concrete technical claim, evidence, impact, and a plausible fix direction.
-7. Return `Status: rejected` if there is at least one real issue that should send the phase back to the implementer. Otherwise, return `Status: approved`.
+7. Return `Status: rejected` if there is at least one real issue that should send the phase back to the worker. Otherwise, return `Status: approved`.
## Output
@@ -55,7 +55,7 @@ Use this exact format for your output.
**Acceptance Criteria Status**
- <criterion>: <met | not met | unclear>
- - Evidence: <brief proof from code, diff, checks, behavior, or missing verification>
+ - Evidence: <brief proof from code, diff, checks, behaviour, or missing verification>
<if findings, include this section>
@@ -74,8 +74,8 @@ Use this exact format for your output.
These rules are MANDATORY.
-- DO NOT trust the implementers self-review report, verify all criteria yourself.
-- ALWAYS check for non-Propulsion skills that are relevant to this task and load them IMMEDIATELY using the skill tool.
+- DO NOT trust the worker's self-review report, verify all criteria yourself.
+- ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY.
- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
- MUST review the actual implementation, not only the report text.
- MUST inspect relevant changed files and the current diff before approving.
@@ -83,7 +83,7 @@ These rules are MANDATORY.
- MUST return exactly one `Status:` line with either `approved` or `rejected`.
- If `Status: rejected`, MUST include at least one finding.
- Findings MUST be ordered by severity, highest first.
-- Findings MUST be evidence-based, actionable, and specific enough for an implementer to verify or challenge technically.
+- Findings MUST be evidence-based, actionable, and specific enough for a worker to verify or challenge technically.
- Prefer exact locations. If you cannot pinpoint a location, say so explicitly instead of guessing.
- DO NOT make code changes; review only.
diff --git a/skills/execution/references/implementation-feedback-prompt.md b/skills/execute/references/worker-feedback-prompt.md
similarity index 88%
rename from skills/execution/references/implementation-feedback-prompt.md
rename to skills/execute/references/worker-feedback-prompt.md
index f77cfc3..308d137 100644
--- a/skills/execution/references/implementation-feedback-prompt.md
+++ b/skills/execute/references/worker-feedback-prompt.md
@@ -1,6 +1,6 @@
# Implementation Feedback Prompt Template
-Use this template when returning review findings to the active implementer subagent in the `execution` skill.
+Use this template when returning review findings to the active worker subagent in the `execute` skill.
````markdown
**You are a subagent completing work in the Propulsion workflow.**
@@ -21,7 +21,7 @@ Follow these steps IN ORDER. Do NOT skip steps.
4. If any finding remains `unclear` after inspecting the plan, codebase, diff, and available evidence, STOP and report `Status: unclear` with a request for specific additional information needed to triage the finding.
5. For every `valid` finding, make the minimal correct fix.
6. For every `invalid` finding, keep the code as-is and prepare evidence-backed pushback.
-7. Load the `tdd` skill NOW if it's NOT already loaded, and follow the guidance when implementing the fixes.
+7. Load the `tdd` skill NOW if it is not already loaded, and follow the guidance when implementing the fixes.
8. Verify your implementation works as intended.
9. Self-review your implementation against the task description and acceptance criteria.
10. Return a report in the exact format defined below.
@@ -55,14 +55,14 @@ Use this exact format for your output.
**Acceptance Criteria Status**:
- <criterion>: <met | not met | unclear>
- - Evidence: <brief proof from diff, test output, behavior, or missing input>
+ - Evidence: <brief proof from diff, test output, behaviour, or missing input>
**Review Feedback Triage**:
- <finding title>
- Classification: <valid | invalid | unclear>
- Resolution: <fixed | rejected with evidence | escalated>
- - Evidence: <brief proof from code, diff, checks, behavior, or missing context>
+ - Evidence: <brief proof from code, diff, checks, behaviour, or missing context>
```
## Rules
diff --git a/skills/execution/references/implementer-prompt.md b/skills/execute/references/worker-prompt.md
similarity index 86%
rename from skills/execution/references/implementer-prompt.md
rename to skills/execute/references/worker-prompt.md
index 165aa33..ffd4e25 100644
--- a/skills/execution/references/implementer-prompt.md
+++ b/skills/execute/references/worker-prompt.md
@@ -1,6 +1,6 @@
-# Implementer Prompt Template
+# Worker Prompt Template
-Use this template when dispatching a fresh implementer subagent in the `execution` skill.
+Use this template when starting a fresh worker subagent in the `execute` skill.
````markdown
**You are a subagent completing work in the Propulsion workflow.**
@@ -18,7 +18,7 @@ You are a senior software engineer implementing the current phase of work define
Follow these steps IN ORDER. Do NOT skip steps.
1. Review the task description above and ask any clarifying questions if the requirements, scope, or repo state are unclear. Do not guess or make assumptions.
-2. Load the `tdd` skill NOW and follow the guidance.
+2. Load the `tdd` skill NOW and follow it.
3. Implement the work for this phase as defined in the task description.
4. Verify your implementation works as intended.
5. Self-review your implementation against the task description and acceptance criteria.
@@ -53,7 +53,7 @@ Use this exact format for your output.
**Acceptance Criteria Status**:
- <criterion>: <met | not met | unclear>
- - Evidence: <brief proof from diff, test output, behavior, or missing input>
+ - Evidence: <brief proof from diff, test output, behaviour, or missing input>
```
## Rules
@@ -63,7 +63,7 @@ These rules are MANDATORY.
- ALWAYS ask questions if anything in the task description is unclear. Do NOT guess or make assumptions.
- DO NOT write any code before fully understanding the requirements, scope, and repo state for the current phase.
- ALWAYS load and use the `tdd` skill.
-- ALWAYS check for non-Propulsion skills that are relevant to this task and load them IMMEDIATELY using the skill tool.
+- ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY.
- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
- Follow the instructions and output format EXACTLY as defined above.
diff --git a/skills/execution/SKILL.md b/skills/execution/SKILL.md
deleted file mode 100644
index 064d5fe..0000000
--- a/skills/execution/SKILL.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-name: execution
-# prettier-ignore
-description: Execute a feature plan by orchestrating fresh subagents one phase at a time. Use when current `plan.md` exists and the user wants feature implementation to start.
----
-
-# Execution
-
-Execute a feature plan one phase at a time.
-
-## Prerequisites
-
-ALL prerequisites MUST be true before following this skill.
-
-- If no `docs/propulsion/.../plan.md` exists for this work, STOP. Load `planning`.
-- If the plan is bug-oriented, STOP. Load `debugging`.
-
-## Instructions
-
-Follow these steps IN ORDER. Do NOT skip steps.
-
-1. Review `plan.md` to understand how each phase is scoped.
-2. Select the first incomplete phase in `plan.md` as the current phase.
-3. Dispatch a fresh implementer subagent with the prompt in [references/implementer-prompt.md](references/implementer-prompt.md).
-4. Wait for the implementer to finish and report back.
-5. If the implementer reports `Status: unclear` then provide additional context or clarification to the implementer.
-6. If the implementer reports `Status: blocked` then triage the blocker and resolve it.
-7. Escalate to the user if you are unable to resolve `unclear` or `blocked` statuses from context within the plan, codebase, or tools.
-8. If the implementer reports `Status: done` then dispatch a fresh implementation-reviewer subagent with the prompt in [references/implementation-reviewer-prompt.md](references/implementation-reviewer-prompt.md).
-9. If the implementation-reviewer reports `Status: rejected`, send the findings back to the same implementer subagent session with the prompt in [references/implementation-feedback-prompt.md](references/implementation-feedback-prompt.md).
-10. Repeat steps 4-9 until the implementer reports `Status: done` and the latest implementation-reviewer reports `Status: approved`.
-11. Check off the current phase acceptance criteria and phase completion in `plan.md`.
-12. Repeat steps 2-11 for the next incomplete phase in `plan.md` until all phases are complete.
-13. After the last phase is complete, infer and run the final repo-wide checks before claiming the plan complete (tests, lint, formatting, build etc., depending on the repo and work).
-
-## Rules
-
-These rules are MANDATORY.
-
-- DO NOT implement work from the main agent, ALWAYS dispatch a fresh implementer subagent for each phase.
-- DO NOT use `execution` for bug diagnosis, bug-fix orchestration, or bug-fix feedback loops; those belong to `debugging`.
-- NEVER resolve `Status: unclear` or `Status: blocked` by guessing. If the information is not in the plan, codebase, or tools, escalate to the user for resolution.
-- ALWAYS update `plan.md` checkboxes after each successful implementation-review cycle.
-- ALWAYS use the prompts in the references when dispatching subagents and sending feedback.
-- You CAN use parallel implementer subagents for different phases ONLY IF the phases are truly independent with no shared dependencies or risk of conflicts.
-- DO NOT claim completion without final repo-wide checks.
-
-## Completion Gate
-
-Do NOT leave this skill until ALL items are complete.
-
-- [ ] Every phase in `plan.md` has gone through an implementer subagent and received `Status: done`.
-- [ ] Every phase in `plan.md` has gone through an implementation-reviewer subagent and received `Status: approved`.
-- [ ] Every phase acceptance criterion and phase completion checkbox in `plan.md` is checked off.
-- [ ] Final repo-wide checks pass.
-- [ ] Completion evidence is provided to the user.
-
-## Next Skill
-
-Once the completion gate is fully checked:
-
-- Tell the user the plan is fully executed and ask whether they have any feedback on the implementation.
-
-## References
-
-Use these references when you need detail.
-
-- [references/implementer-prompt.md](references/implementer-prompt.md) - Fresh implementer subagent prompt.
-- [references/implementation-reviewer-prompt.md](references/implementation-reviewer-prompt.md) - Fresh implementation-reviewer subagent prompt.
-- [references/implementation-feedback-prompt.md](references/implementation-feedback-prompt.md) - Prompt for sending implementation-reviewer findings back to the implementer subagent.
diff --git a/skills/exploration/SKILL.md b/skills/exploration/SKILL.md
deleted file mode 100644
index 6be9da5..0000000
--- a/skills/exploration/SKILL.md
+++ /dev/null
@@ -1,65 +0,0 @@
----
-name: exploration
-# prettier-ignore
-description: Create an approved PRD through repo inspection and relentless user questioning. Use when scope, UX, constraints, or success criteria are unclear, or when user needs a PRD.
----
-
-# Exploration
-
-Turn vague work into an approved PRD, including bug work that still needs expected-behaviour capture before implementation planning.
-
-## Prerequisites
-
-ALL prerequisites MUST be true before following this skill.
-
-- If an approved `docs/propulsion/.../prd.md` already exists for this work, STOP. Load `planning`.
-
-## Instructions
-
-Follow these steps IN ORDER. Do NOT skip steps.
-
-1. Start with a targeted exploration of the codebase using fresh explore subagents for code facts.
-2. Walk down each branch of the decision tree, interviewing the user relentlessly until every branch is closed, and you have a shared understanding of the work.
-3. Ask each question using the `question` tool, one at a time, and provide your recommended answer first.
-4. If a question can be answered by inspecting the codebase, do that instead of asking the user.
-5. If the request is too large, decompose it and explore only the first phase or subsystem.
-6. After all blocking branches are closed and exploration is complete, check for relevant non-Propulsion skills and load them before writing `prd.md`.
-7. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` using the template in [references/prd-template.md](references/prd-template.md).
-8. Ask the user to review and approve `prd.md` before loading `planning`.
-
-## Rules
-
-These rules are MANDATORY.
-
-- ALWAYS interview the user RELENTLESSLY to close branches, ask as many questions as it takes to get a shared understanding.
-- MUST close every blocking branch before writing `prd.md`. Blocking branches include anything that would change scope, UX, architecture, sequencing, or success criteria.
-- BEFORE writing `prd.md`, ALWAYS check for non-Propulsion skills that are relevant to this task and load them IMMEDIATELY using the skill tool.
-- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
-- MUST keep the PRD product-facing while recording durable implementation and testing decisions.
-- ENSURE the PRD includes ALL relevant decisions, even if they seem obvious or minor.
-- You CAN create supporting documents such as `docs/propulsion/.../research.md` or `docs/propulsion/.../diagrams.md` if needed, but the PRD must include all durable decisions.
-- DO include the supporting documents as implementation inputs in the PRD, but DO NOT rely on them for durable decisions.
-- DO NOT print the PRD, plan, or other workflow artefact content in chat instead of writing files.
-- DO NOT start `planning` here.
-- If you cannot write files, STOP, ask the user to switch to build mode, and tell them to return to `exploration` so you can write `prd.md`.
-
-## Completion Gate
-
-Do NOT leave this skill until ALL items are complete.
-
-- [ ] Targeted exploration of the codebase is complete.
-- [ ] Blocking decision tree branches are closed.
-- [ ] `prd.md` written to `docs/propulsion/.../prd.md`.
-- [ ] User asked to review and approve `prd.md`.
-
-## Next Skill
-
-Once the completion gate is fully checked:
-
-- If `prd.md` is approved, load `planning`.
-
-## References
-
-Use these references when you need detail.
-
-- [references/prd-template.md](references/prd-template.md) - PRD shape and output path.
diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md
new file mode 100644
index 0000000..42761b9
--- /dev/null
+++ b/skills/init-project/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: init-project
+description: Create or prune AGENTS.md into minimal global steering for agents. Use when initializing, updating, or reducing repo-wide agent rules.
+---
+
+# Init Project
+
+Create or prune `AGENTS.md` as a tiny global protocol, not a repository overview.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Launch a fresh explorer subagent to inspect the repository before editing: existing `AGENTS.md` files, package/tool configs, docs, scripts, and visible conventions that could make proposed rules discoverable.
+2. Load the `interrogate` skill to gather global, non-discoverable instructions the repository cannot reveal, including human protocol, hidden operational landmines, environment gotchas, and mandatory verification timing.
+3. Preserve or add the default correction rule near the top of `AGENTS.md`.
+4. Apply the line admission test to every candidate rule: global, non-discoverable, and operationally important.
+5. Challenge weak or bloated candidate instructions before keeping them; remove any rule that fails the admission test or belongs in code, config, docs, skills, or commands.
+6. Draft the smallest useful `AGENTS.md`, keeping always-followed rules near the top.
+7. Handoff with the changed file path plus kept, removed, and challenged rule categories.
+
+## Rules
+
+These rules are MANDATORY.
+
+- MUST launch a fresh explorer subagent before creating, pruning, or rewriting `AGENTS.md`.
+- MUST use `interrogate` skill for human-only, repo-wide rules that repository inspection cannot discover.
+- MUST keep only rules that pass all three admission checks: global, non-discoverable, operationally important.
+- MUST challenge or remove vague, task-specific, discoverable, duplicated, or low-impact instructions.
+- MUST use this default correction rule: "- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`."
+- DO NOT include tech stack summaries, folder maps, command inventories, architecture recaps, or style rules already enforced by tooling.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Fresh explorer subagent completed repository inspection before edits.
+- [ ] `interrogate` skill was used for non-discoverable global rules or existing user-provided rules were explicitly classified.
+- [ ] Default correction rule is present once and near the top.
+- [ ] Every retained non-default line passes the admission test.
+- [ ] Weak or bloated candidates were challenged or removed.
+- [ ] Intended `AGENTS.md` behaviour is preserved and summarised before handoff.
+
+## References
+
+Use these references when you need detail.
+
+- [references/process.md](references/process.md) - End-to-end creation and pruning process for minimal `AGENTS.md` files.
+- [references/examples.md](references/examples.md) - Good examples, pruning examples, and anti-patterns.
diff --git a/skills/init-project/references/examples.md b/skills/init-project/references/examples.md
new file mode 100644
index 0000000..b9faf1a
--- /dev/null
+++ b/skills/init-project/references/examples.md
@@ -0,0 +1,86 @@
+# AGENTS.md Examples
+
+These examples show minimal protocol-style `AGENTS.md` files and pruning decisions.
+
+## Default Rule Only
+
+Use this when no repo-specific rule passes the admission test.
+
+```markdown
+# AGENTS.md
+
+- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`.
+```
+
+## Environment Gotcha
+
+Keep invisible environment constraints that can cause repeated failures.
+
+```markdown
+# AGENTS.md
+
+- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`.
+- This repo is developed inside a Linux container mounted from macOS; run file-watching commands inside the container to avoid missed changes.
+```
+
+## Hidden Landmine
+
+Keep repo-wide operational facts that code structure hides.
+
+```markdown
+# AGENTS.md
+
+- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`.
+- `legacy/` appears unused but is imported dynamically in production; do not delete or bulk-move it without explicit approval.
+- Never regenerate checked-in fixtures in `fixtures/prod/`; they are hand-sanitized production snapshots.
+```
+
+## Pruning Examples
+
+Remove discoverable project summaries:
+
+```markdown
+- This project uses Bun, TypeScript, and React.
+```
+
+Reason: package and config files reveal the stack.
+
+Keep mandatory verification timing when the obligation or timing is not discoverable:
+
+```markdown
+- After implementing changes run `bun run test` before handoff.
+```
+
+Reason: this is not a command inventory; it defines mandatory per-change timing that scripts alone do not reveal.
+
+Remove command inventories:
+
+```markdown
+- Run `bun test` for tests and `bun run lint` for linting.
+```
+
+Reason: scripts and CI already document commands. Keep only a non-discoverable command caveat, such as a cache flag required to avoid false positives.
+
+Challenge vague preferences:
+
+```markdown
+- Write clean code and keep files organized.
+```
+
+Reason: not operationally specific. Ask for a concrete repo-wide failure mode or delete it.
+
+Relocate task-specific workflow:
+
+```markdown
+- For payment changes, update the billing PRD and run card network sandbox tests.
+```
+
+Reason: not global to every task. Move to a domain skill, command, or docs unless it truly applies to all sessions.
+
+## Anti-Patterns
+
+- Architecture overviews copied from docs or inferred from folders.
+- Full setup instructions copied from README.
+- Formatting or naming rules already enforced by tooling.
+- Multiple paragraphs explaining why a rule exists inside `AGENTS.md`.
+- Product-specific agent instructions instead of generic agent protocol.
diff --git a/skills/init-project/references/process.md b/skills/init-project/references/process.md
new file mode 100644
index 0000000..613d954
--- /dev/null
+++ b/skills/init-project/references/process.md
@@ -0,0 +1,83 @@
+# Minimal AGENTS.md Process
+
+Use this workflow when creating, pruning, or updating `AGENTS.md` under the strict minimal-context policy.
+
+## 1. Inspect Before Editing
+
+Launch a fresh explorer subagent to read enough repository evidence to avoid duplicating discoverable facts:
+
+- Existing `AGENTS.md` files, including parent or nested files that may apply.
+- Package manifests, task runners, Makefiles, build files, and test configs.
+- Formatter, linter, TypeScript, CI, and editor config.
+- Docs that already describe setup, scripts, architecture, or conventions.
+- Source layout and naming patterns when they answer a proposed rule.
+
+Do not add repository summaries. Inspection exists to identify what does not belong in `AGENTS.md`.
+
+## 2. Ask For Invisible Rules
+
+Use the existing `interrogate` skill to ask the user for rules the repository cannot reliably reveal. Focus on:
+
+- Human protocol that must persist across sessions.
+- Hidden operational landmines, unsafe directories, or legacy coupling.
+- Environment quirks not encoded in config.
+- Repo-wide constraints not enforced by code, tests, lint, CI, or docs.
+- Mandatory verification timing that applies to every change but is not reliably encoded in scripts, docs, or CI.
+
+If the user gives candidate rules, classify them instead of accepting them uncritically.
+
+## 3. Preserve The Default Correction Rule
+
+Keep this rule near the top, even when it is the only surviving rule:
+
+```markdown
+- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`.
+```
+
+Do not keep older variants that prescribe loading a skill or editing the file after the user answers. Replace them with the ask-only wording.
+
+## 4. Apply The Admission Test
+
+Keep every non-default line only if all checks pass:
+
+- Global: applies to every task or session in this repository.
+- Non-discoverable: an agent cannot reliably infer it from repository files, tooling, docs, or scripts.
+- Operationally important: missing it is likely to cause mistakes, wasted effort, unsafe edits, or broken workflow.
+
+Mandatory per-change verification timing can pass the non-discoverable check when the obligation or handoff timing is not reliably encoded in tooling, scripts, docs, or CI.
+
+If any check fails, challenge the rule or remove it.
+
+## 5. Challenge Weak Instructions
+
+Push back on candidates that are:
+
+- Discoverable from source, config, package files, or docs.
+- Task-specific workflows that belong in a skill, command, issue, or PRD.
+- Style preferences enforced by formatter, linter, types, or tests.
+- Generic good advice that applies to all repositories.
+- Vague intent without operational consequence.
+- Bloated multi-line explanations that can be compressed into one actionable rule.
+
+When challenging, explain the failed admission check and suggest the smaller replacement, a better home, or deletion.
+
+## 6. Draft The Smallest Useful File
+
+Prefer a short protocol file:
+
+1. Put the default correction rule first or near the top.
+2. Put always-followed repo-wide rules immediately after it.
+3. Group only when grouping improves scanning; avoid section filler.
+4. Keep only the final accepted rules, not the rationale.
+5. If nothing repo-specific qualifies, leave a one-rule file.
+
+## 7. Validate Before Handoff
+
+Before finishing, verify:
+
+- The default correction rule appears exactly once and is ask-only.
+- Every retained non-default line passes the admission test.
+- Discoverable facts are not duplicated from repository evidence.
+- Always-followed rules remain near the top.
+- Existing intended behaviour is preserved unless explicitly removed after challenge.
+- Handoff reports kept, removed, challenged, and relocated categories.
diff --git a/skills/interrogate/SKILL.md b/skills/interrogate/SKILL.md
new file mode 100644
index 0000000..29a631c
--- /dev/null
+++ b/skills/interrogate/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: interrogate
+# prettier-ignore
+description: Manage interrogation, intake, interviews, scope clarification, requirements gathering, and shared understanding. Use when missing decisions must be resolved.
+---
+
+# Interrogate
+
+Reach shared understanding by interrogating one decision at a time, backed by available project context.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Start every interrogation session by launching a fresh explorer subagent to inspect available project context for facts relevant to the request.
+2. Build the decision tree for the request, then walk down each branch that could affect the answer or next action.
+3. Close any branch the project can answer through a focused explorer subagent instead of asking the user.
+4. Ask the user questions for each unresolved branch, using the format in [references/interrogate-protocol.md](references/interrogate-protocol.md).
+5. Update the decision tree after each answer, then repeat focused explorer-subagent exploration or user interrogation until shared understanding is reached.
+6. Return the handoff summary format in [references/interrogate-protocol.md](references/interrogate-protocol.md) before handing control back to the caller.
+
+## Rules
+
+These rules are MANDATORY.
+
+- MUST keep this skill chat-only; DO NOT create or edit durable artefacts from this skill.
+- MUST ask exactly one user question at a time.
+- MUST relentlessly continue user interrogation until shared understanding is reached; there is no limit on the number of questions.
+- MUST provide the recommended answer first, then 2-3 viable alternatives.
+- MUST use explorer subagents for entry exploration and focused project-answerable questions.
+- DO NOT ask the user questions that codebase inspection can answer.
+- MUST walk the decision tree until every blocking branch is closed by project facts or user answers.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Fresh explorer subagent completed entry project-context inspection.
+- [ ] Decision tree branches were explored and attempted to answer with code exploration.
+- [ ] Remaining open branches were closed by relentlessly interrogating the user.
+- [ ] Shared understanding was reached with no open blocking branches.
+- [ ] Resolved decisions were summarised for the caller.
+
+## References
+
+Use these references when you need detail.
+
+- [references/interrogate-protocol.md](references/interrogate-protocol.md) - Detailed intake protocol, question format, and branch handling.
diff --git a/skills/interrogate/references/interrogate-protocol.md b/skills/interrogate/references/interrogate-protocol.md
new file mode 100644
index 0000000..25981c6
--- /dev/null
+++ b/skills/interrogate/references/interrogate-protocol.md
@@ -0,0 +1,52 @@
+# Interrogate Protocol
+
+Use this protocol when a workflow needs missing information resolved before it can proceed safely.
+
+## Entry Exploration
+
+Launch a fresh explorer subagent to inspect available project context before asking the user anything. Use the user's request, the current workflow goal, and any facts needed to avoid asking questions the project can answer. Use those findings to seed the initial decision tree.
+
+## Decision Tree
+
+Track unresolved branches, then walk down each branch of the decision tree that could affect the answer or next action. Work the highest-impact blocking branch first. A branch is closed only when it is answered by project facts or answered by the user.
+
+## Codebase-Answerable Branches
+
+Before asking the user, decide whether project inspection could answer the branch. If yes, launch a focused explorer subagent with one narrow objective. Use focused project exploration for existing patterns, available APIs, file locations, naming conventions, tests, configuration, dependencies, and shipped behaviour.
+
+## User Question Format
+
+Relentlessly ask the user one question at a time. Keep each question decision-oriented and easy to answer. There is no limit on the number of questions; keep going until shared understanding is reached.
+
+```markdown
+Question: <single question the user must decide>
+
+Recommendation: <best answer and why it fits the current facts>
+
+Options:
+
+- <recommended option, repeated concisely>
+- <viable alternative 1>
+- <viable alternative 2, if useful>
+- <viable alternative 3, only if genuinely viable>
+```
+
+Do not list more than 3 alternatives beyond the recommendation. Do not ask multi-part questions. If multiple decisions are related, ask the prerequisite decision first and let the next branch depend on that answer.
+
+## Shared Understanding
+
+Continue walking the decision tree until no blocking branches remain. Shared understanding means the agent can state the intended outcome, constraints, important tradeoffs, and the next workflow action without inventing product or codebase facts.
+
+## Handoff Summary
+
+When interrogation is complete, return a concise summary to the caller. Keep the summary in chat; this skill does not create or edit durable artefacts.
+
+```markdown
+Resolved decisions:
+
+- <decision>
+
+Project facts:
+
+- <fact learned from exploration>
+```
diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md
new file mode 100644
index 0000000..1f7b445
--- /dev/null
+++ b/skills/plan/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: plan
+# prettier-ignore
+description: Create an implementation-ready feature plan from an approved PRD using phases scoped as thin vertical slices. Use when an approved `docs/propulsion/.../prd.md` exists.
+---
+
+# Plan
+
+Turn an approved PRD into a phased implementation-ready plan using vertical slices.
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- If a `docs/propulsion/.../plan.md` already exists for this work, STOP. Ask the user whether to enter `execute`.
+- If no approved `docs/propulsion/.../prd.md` exists, STOP. Enter the `brainstorm` skill.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Review the approved `prd.md` to understand the requirements.
+2. Explore relevant areas of the codebase for fresh context.
+3. Identify high-level durable decisions that are unlikely to change throughout implementation.
+4. Identify narrow vertical slices that cut through all integration layers end-to-end.
+5. Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` using the template in [references/plan-template.md](references/plan-template.md).
+6. Start a plan review in a fresh subagent with the prompt in [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md).
+7. Review and implement feedback from the plan review.
+8. Repeat steps 6 and 7 until the review returns `Status: approved`.
+9. Tell the user the plan is complete and ask whether to move to `execute`.
+
+## Rules
+
+These rules are MANDATORY.
+
+- MUST output the `plan.md` in the exact shape specified in the template reference.
+- DO NOT output the plan in the chat, ONLY in the `plan.md` file.
+- MUST keep phases thin, ordered, and implementation-ready.
+- DO NOT lose ANY information from the PRD that is relevant to implementation; lost information risks misalignment and rework.
+- MUST treat `Status: approved` as the only valid approval signal for implementation readiness.
+- MUST treat `findings` as fixable plan issues inside `plan`.
+- MUST apply `suggestions` when they make implementation smoother.
+- DO NOT invent missing product decisions.
+- DO NOT auto-start `execute`; ALWAYS ask the user whether to proceed.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] PRD reviewed.
+- [ ] Relevant codebase areas explored for fresh context.
+- [ ] `plan.md` written to `docs/propulsion/.../plan.md`.
+- [ ] Plan review by a subagent returns `Status: approved`.
+- [ ] User asked whether to move to `execute`.
+
+## Next Steps
+
+Once the completion gate is fully checked:
+
+- If the user says to proceed, enter the `execute` skill.
+- If product intent is missing, enter the `brainstorm` skill.
+
+## References
+
+Use these references when you need detail.
+
+- [references/plan-template.md](references/plan-template.md) - Plan shape and phase format.
+- [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md) - Plan-reviewer subagent prompt.
diff --git a/skills/planning/references/plan-reviewer-prompt.md b/skills/plan/references/plan-reviewer-prompt.md
similarity index 67%
rename from skills/planning/references/plan-reviewer-prompt.md
rename to skills/plan/references/plan-reviewer-prompt.md
index 140ab48..a2a30bd 100644
--- a/skills/planning/references/plan-reviewer-prompt.md
+++ b/skills/plan/references/plan-reviewer-prompt.md
@@ -1,6 +1,6 @@
# Plan Reviewer Prompt Template
-Use this template when dispatching a fresh plan-reviewer subagent in the `planning` skill.
+Use this template when starting plan review in a fresh subagent from the `plan` skill.
````markdown
**You are a subagent completing work in the Propulsion workflow.**
@@ -12,18 +12,17 @@ You are a plan document reviewer. Verify that the plan is implementation ready.
## Review Criteria
-| Category | What to verify |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Source Alignment | The plan preserves all information from the PRD within the relevant phases, no information is lost. |
-| Behaviour Coverage | The end-to-end user behaviour is covered coherently; no important flow, transition, or outcome is missing. |
-| Scope Control | Required work is included, and speculative or non-goal work is excluded. |
-| Phase Design | Phases are thin vertical slices delivering narrow end-to-end behaviour, not horizontal layers or vague milestones. |
-| Sequencing & Dependencies | Phase order is workable, dependencies are respected, and the plan will not force rework or dead ends later. |
-| Phase Specificity | Each phase gives the downstream implementer or debugger enough context to act: clear goal, likely areas, constraints, and acceptance criteria. |
-| Stage Handoff | Bug-oriented plans hand off diagnosis and fix orchestration to `debugging`, while feature-oriented plans hand off implementation to `execution`. |
-| Decision Hygiene | Durable decisions are captured once at the right level, with no contradictions or re-litigation points across phases. |
+| Category | What to verify |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Source Alignment | The plan preserves all information from the PRD within the relevant phases, no information is lost. |
+| Behaviour Coverage | The end-to-end user behaviour is covered coherently; no important flow, transition, or outcome is missing. |
+| Scope Control | Required work is included, and speculative or non-goal work is excluded. |
+| Phase Design | Phases are thin vertical slices delivering narrow end-to-end behaviour, not horizontal layers or vague milestones. |
+| Sequencing & Dependencies | Phase order is workable, dependencies are respected, and the plan will not force rework or dead ends later. |
+| Phase Specificity | Each phase gives the worker enough context to act: clear goal, likely areas, constraints, and acceptance criteria. |
+| Decision Hygiene | Durable decisions are captured once at the right level, with no contradictions or re-litigation points across phases. |
-Flag only issues that would cause downstream work to build the wrong thing, get stuck, or need re-planning.
+Flag only issues that would cause implementation to build the wrong thing, get stuck, or need re-planning.
## Instructions
@@ -31,10 +30,9 @@ Follow these steps IN ORDER. Do NOT skip steps.
1. Review the plan against the source PRD for implementation-readiness.
2. Use the review criteria table above to guide your review.
-3. Categorise issues that would cause real problems during downstream implementation or debugging as `findings`.
-4. Categorise issues that are more about improving downstream readiness without blocking the next stage as `suggestions`.
-5. For bug-oriented plans, confirm the plan hands off diagnosis and fix orchestration to `debugging`. For feature-oriented plans, confirm it hands off implementation to `execution`.
-6. Return your findings and suggestions in the exact format below.
+3. Categorise issues that would cause real problems during implementation as `findings`.
+4. Categorise issues that are more about improving implementation readiness without blocking the next stage as `suggestions`.
+5. Return your findings and suggestions in the exact format below.
## Output
@@ -61,7 +59,7 @@ Use this exact format for your output.
- <suggestion>
- Phase or section affected: <phase name or section name>
- - Why it matters: <short explanation of how this suggestion would improve downstream readiness>
+ - Why it matters: <short explanation of how this suggestion would improve implementation readiness>
</if suggestions, include this section>
```
@@ -71,14 +69,14 @@ Use this exact format for your output.
These rules are MANDATORY.
- Replace the plan and PRD paths with the actual paths for the plan being reviewed.
-- ALWAYS check for non-Propulsion skills that are relevant to this task and load them IMMEDIATELY using the skill tool.
+- ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY.
- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
- MUST return exactly one `Status:` line with either `approved` or `rejected`.
- Status CAN be `approved` if there are only suggestions but NO findings.
- If returning `Status: rejected`, MUST include at least one finding.
- Findings MUST be specific issues that would block or misdirect the next stage, not vague or general feedback.
-- Suggestions are optional, but if included, MUST be specific improvements that would increase downstream readiness.
-- Be specific about which phase or section each finding or suggestion relates to, and why it matters for downstream readiness.
+- Suggestions are optional, but if included, MUST be specific improvements that would increase implementation readiness.
+- Be specific about which phase or section each finding or suggestion relates to, and why it matters for implementation readiness.
- DO NOT update the plan document or source PRD, only review and provide feedback in this output.
## Completion Gate
diff --git a/skills/planning/references/plan-template.md b/skills/plan/references/plan-template.md
similarity index 79%
rename from skills/planning/references/plan-template.md
rename to skills/plan/references/plan-template.md
index 55cd639..c700049 100644
--- a/skills/planning/references/plan-template.md
+++ b/skills/plan/references/plan-template.md
@@ -9,7 +9,7 @@ Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` using this shape.
## For Agentic Coders
-Use the <`execution` | `debugging`> skill to implement this plan and track progress using the checkboxes.
+Use the `execute` skill to implement this plan and track progress using the checkboxes.
## Durable Decisions
@@ -65,5 +65,4 @@ Use the <`execution` | `debugging`> skill to implement this plan and track progr
- Keep durable decisions out of the phases when they apply globally.
- Use exact file paths only when they are durable and important.
- Copy the relevant `**User Stories**:` into each phase from the approved PRD.
-- Give each phase enough context that a fresh subagent does not need to rediscover scope.
-- Choose the downstream skill based on the plan's content and PRD context. If the plan is feature-oriented, it should hand off to `execution`. If the plan is bug-oriented, it should hand off to `debugging`.
+- Give each phase enough context that a subagent does not need to rediscover scope.
diff --git a/skills/planning/SKILL.md b/skills/planning/SKILL.md
deleted file mode 100644
index c6a9f25..0000000
--- a/skills/planning/SKILL.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-name: planning
-# prettier-ignore
-description: Create an implementation-ready plan from an approved PRD using phases scoped as thin vertical slices. Use when an approved `docs/propulsion/.../prd.md` exists and the next step is to create a feature or bug implementation plan.
----
-
-# Planning
-
-Turn an approved PRD into a phased implementation-ready plan using vertical slices.
-
-## Prerequisites
-
-ALL prerequisites MUST be true before following this skill.
-
-- If a `docs/propulsion/.../plan.md` already exists for this work, STOP. Determine whether the plan is feature-oriented or bug-oriented, then ask the user whether to load the correct downstream skill: `execution` for feature work or `debugging` for bug work.
-- If no approved `docs/propulsion/.../prd.md` exists, STOP. Load `exploration`.
-
-## Instructions
-
-Follow these steps IN ORDER. Do NOT skip steps.
-
-1. Review the approved `prd.md` to understand the requirements.
-2. Explore relevant areas of the codebase for fresh context.
-3. Identify high-level durable decisions that are unlikely to change throughout implementation.
-4. Identify narrow vertical slices that cut through all integration layers end-to-end.
-5. Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` using the template in [references/plan-template.md](references/plan-template.md).
-6. Dispatch a fresh plan-reviewer subagent with the prompt in [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md).
-7. Review and implement feedback from the plan-reviewer subagent.
-8. Repeat steps 6 and 7 until the review returns `Status: approved`.
-9. Tell the user planning is complete, state whether the work is feature-oriented or bug-oriented, and ask whether to move to the correct downstream skill: `execution` for feature work or `debugging` for bug work.
-
-## Rules
-
-These rules are MANDATORY.
-
-- MUST output the `plan.md` in the exact shape specified in the template reference.
-- DO NOT output the plan in the chat, ONLY in the `plan.md` file.
-- MUST keep phases thin, ordered, and implementation-ready.
-- MUST make the plan's downstream ownership explicit: `execution` for feature implementation, `debugging` for bug diagnosis and bug-fix loops.
-- MUST determine the downstream skill from the plan and PRD context. DO NOT ask the user to choose between `execution` and `debugging`.
-- DO NOT loose ANY information from the PRD that is relevant to implementation, otherwise you risk misalignment and rework.
-- MUST treat `Status: approved` as the only valid approval signal for downstream readiness.
-- MUST treat `findings` as fixable planning issues inside `planning`.
-- MUST treat `suggestions` as improvable aspects that should be implemented IF they make downstream implementation or debugging smoother.
-- DO NOT invent missing product decisions.
-- DO NOT auto-start `execution` or `debugging`, ALWAYS ask the user whether to proceed.
-
-## Completion Gate
-
-Do NOT leave this skill until ALL items are complete.
-
-- [ ] PRD reviewed.
-- [ ] Relevant codebase areas explored for fresh context.
-- [ ] `plan.md` written to `docs/propulsion/.../plan.md`.
-- [ ] Plan-reviewer subagent returns `Status: approved`.
-- [ ] User asked whether to move to the correct downstream skill for the work.
-
-## Next Skill
-
-Once the completion gate is fully checked:
-
-- If the plan is feature-oriented and the user says to proceed, load `execution`.
-- If the plan is bug-oriented and the user says to proceed, load `debugging`.
-- If product intent is missing, load `exploration`.
-
-## References
-
-Use these references when you need detail.
-
-- [references/plan-template.md](references/plan-template.md) - Plan shape and phase format.
-- [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md) - Fresh plan-reviewer subagent prompt.
diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md
new file mode 100644
index 0000000..4d6141a
--- /dev/null
+++ b/skills/pr/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: pr
+description: Create or reuse a GitHub pull request from the current branch with safe commit and push. Use when opening, updating, or reporting a PR.
+---
+
+# Pull Request
+
+Create or reuse one GitHub pull request from the current branch and report the verified result.
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- GitHub CLI `gh` is installed and authenticated for the target repository.
+- The current directory is a git repository with an `origin` remote.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Resolve the base branch from optional user input, or default to the repo's main development branch.
+2. Collect context first with the git commands in [references/workflow.md](references/workflow.md).
+3. If the current branch equals the base branch, stop and ask the user to confirm the intended base branch.
+4. If the worktree is dirty, load and invoke the `commit` skill with no extra instructions, then refresh branch context before PR metadata.
+5. Push safely: use `git push -u origin <branch>` when no upstream exists; otherwise use `git push`.
+6. Check for an existing open PR for the current head branch.
+7. If an open PR exists with a different base, stop and ask whether to update the base; only if confirmed, run `gh pr edit --base <base>` before title or body refresh.
+8. If an open PR exists on the chosen base, reuse it unchanged when no commit delta exists; otherwise ask whether to refresh title and body, then use `gh pr edit` only after explicit confirmation.
+9. If no open PR exists and no commit delta exists, output exactly `No PR changes to open.`
+10. Generate a Conventional Commit PR title and summary body from the complete `<base>...HEAD` history and diff.
+11. Create the PR with `gh pr create --base <base> --title "<title>" --body "<body>"` when no reusable open PR exists.
+12. Verify the final PR with `gh pr view --json url,number,title,baseRefName,headRefName,state` and return the output contract.
+
+## Rules
+
+These rules are MANDATORY.
+
+- ALWAYS collect context before committing, pushing, creating, editing, or reusing a PR.
+- MUST use the complete branch history and diff, not only the latest commit, for title and body.
+- MUST keep the PR title a valid Conventional Commit subject suitable for squash merge history.
+- NEVER force push, reset, amend older commits, change git config, or bypass hooks.
+- ALWAYS stop and report the failing command plus one concrete unblock action for GitHub CLI auth, permission, or remote access failures.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Base branch, current branch, status, history, diff, and diff stat were collected.
+- [ ] Dirty worktree was handled through the `commit` skill, or no dirty work existed.
+- [ ] Push completed without force, or the workflow stopped for auth, permission, or access action.
+- [ ] Existing PR reuse or refresh rules were followed, or a new PR was created.
+- [ ] Final PR state was verified with `gh pr view`.
+- [ ] Final response matches the required contract in [references/workflow.md](references/workflow.md).
+
+## References
+
+Use these references when you need detail.
+
+- [references/workflow.md](references/workflow.md) - Commands, PR metadata rules, body shape, and output contract.
diff --git a/skills/pr/references/workflow.md b/skills/pr/references/workflow.md
new file mode 100644
index 0000000..1df9c80
--- /dev/null
+++ b/skills/pr/references/workflow.md
@@ -0,0 +1,106 @@
+# Pull Request Workflow Reference
+
+## Inputs
+
+- Optional base branch input: treat any explicit user-provided branch name as `<base>`.
+- If no base is provided, use the repo's main development branch, such as `main` or the branch pointed to by `origin/HEAD`.
+
+## Context Commands
+
+Collect context before any mutation:
+
+- `git status --short`
+- `git branch --show-current`
+- `git log --oneline <base>...HEAD`
+- `git diff <base>...HEAD`
+- `git diff --stat <base>...HEAD`
+
+After invoking the `commit` skill for a dirty worktree, refresh:
+
+- `git status --short`
+- `git log --oneline <base>...HEAD`
+- `git diff <base>...HEAD`
+- `git diff --stat <base>...HEAD`
+
+## Existing PR Handling
+
+Check for an existing open PR for the current head branch:
+
+```sh
+gh pr list --head <branch> --state open --json url,number,title,body,baseRefName,headRefName
+```
+
+- If the PR base differs from `<base>`, stop and ask whether to correct the PR base.
+- If the user explicitly agrees, update the base before any title or body refresh: `gh pr edit --base <base>`.
+- If the user declines or gives an unclear answer, stop and ask them to rerun the PR skill with the intended base branch.
+- If the PR base matches `<base>` and no commit delta exists, reuse the PR unchanged, verify it, and report the success output.
+- If the PR base matches `<base>` and a commit delta exists, show the URL and ask whether to refresh title and summary.
+- If the user explicitly agrees, update only title and body with `gh pr edit --title "<title>" --body "<body>"`.
+- If the user declines or gives an unclear answer, reuse the PR unchanged, verify it, and report the success output.
+
+## Push Safety
+
+- If the branch has no upstream, run `git push -u origin <branch>`.
+- If the branch has an upstream, run `git push`.
+- Never force push.
+- If push fails because authentication, permissions, or remote access requires user action, stop and report the failing command with one concrete unblock action.
+
+## PR Metadata
+
+Infer the title and summary from the full `<base>...HEAD` commit history, diff, and diff stat.
+
+Allowed Conventional Commit title types:
+
+- `build`: production dependencies or build-system changes
+- `chore`: maintenance, admin, or dev-only dependency work
+- `ci`: CI or automation pipeline changes
+- `docs`: documentation-only changes
+- `feat`: a new feature or functionality
+- `fix`: a bug fix for incorrect behaviour
+- `perf`: a performance improvement
+- `refactor`: code changes without behaviour changes
+- `revert`: reverts an earlier change
+- `style`: formatting or style-only clean-up
+- `test`: adds or updates tests
+
+Make the title a valid Conventional Commit subject suitable for squash merge history.
+
+Use this exact PR body shape:
+
+```md
+## Summary
+
+- <bullet derived from the full PR scope>
+```
+
+If no open PR exists, create one with:
+
+```sh
+gh pr create --base <base> --title "<title>" --body "<body>"
+```
+
+Verify the final PR with:
+
+```sh
+gh pr view --json url,number,title,baseRefName,headRefName,state
+```
+
+## No Changes Output
+
+If no open PR exists and no commit delta exists against the base branch, output exactly:
+
+```md
+No PR changes to open.
+```
+
+## Success Output
+
+When PR creation or reuse succeeds, output exactly:
+
+```md
+PR URL: <url>
+Title: <final PR title>
+Base branch: <base>
+Head branch: <head>
+State: <state>
+```
diff --git a/skills/propulsion-workflow/SKILL.md b/skills/propulsion-workflow/SKILL.md
deleted file mode 100644
index 80c9a6d..0000000
--- a/skills/propulsion-workflow/SKILL.md
+++ /dev/null
@@ -1,69 +0,0 @@
----
-name: propulsion-workflow
-# prettier-ignore
-description: Manage software-work request routing into Propulsion before any downstream skill is loaded. Use when starting a session with software work.
----
-
-# Using Propulsion Workflow
-
-Use `propulsion-workflow` to route software-work requests into Propulsion before any other response or action.
-
-<SUBAGENT_STOP>
-If you were dispatched as a subagent to execute a specific task, SKIP THIS SKILL.
-</SUBAGENT_STOP>
-
-<EXTREMELY_IMPORTANT>
-If the user request is software work, `propulsion-workflow` applies before any clarifying question, repo scan, tool call, or downstream Propulsion skill.
-
-If `propulsion-workflow` applies, you MUST route first. Do NOT reload `propulsion-workflow`. Do NOT skip it because the task looks small, obvious, or familiar.
-
-ONCE YOU ARE FOLLOWING PROPULSION WORKFLOW, DO NOT LEAVE IT UNTIL COMPLETION. DO NOT SKIP STEPS. FOLLOW THE RULES OF EACH SKILL.
-</EXTREMELY_IMPORTANT>
-
-## Instruction Priority
-
-1. User instructions, repository rules, and `AGENTS.md`
-2. Propulsion skills
-3. Default system behaviour
-
-## The Rule
-
-Route ALL software-work requests to the `exploration` skill first, that is the entry point for the Propulsion workflow and owns the stage.
-
-For non-software-work requests, DO NOT use Propulsion. Respond normally.
-
-## Required Response
-
-For software-work requests using Propulsion workflow, emit this exact line before any other user-visible text:
-
-`Propulsion workflow enabled, routing to exploration...`
-
-This signals to the user that Propulsion is handling their request and sets expectations for the next steps.
-
-## Sequence
-
-Follow these steps IN ORDER. Do NOT skip steps.
-
-1. Determine whether the request is software work.
-2. If it is not software work, ignore Propulsion and respond normally.
-3. If it is software work, choose `exploration` as the entry point.
-4. Emit `Propulsion workflow enabled, routing to exploration...` before any other user-visible text.
-5. Load the `exploration` skill immediately.
-6. Stop routing. The loaded Propulsion skill now owns the workflow stage.
-
-## Red Flags
-
-- "I need more context first." False. Route first.
-- "I'll inspect the repo first." False. Route first.
-- "This is too small for Propulsion." False. Route first.
-- "I already know the later skill." False. `propulsion-workflow` still owns entry.
-
-## Completion Gate
-
-Do not leave this skill until ALL items are complete.
-
-- [ ] Determined whether the request is software work.
-- [ ] Kept non-software-work chat outside Propulsion.
-- [ ] Routed software work to `exploration`.
-- [ ] Emitted `Propulsion workflow enabled, routing to exploration...` before any other user-visible text.
-- [ ] Loaded the `exploration` skill immediately.
diff --git a/skills/propulsion/SKILL.md b/skills/propulsion/SKILL.md
new file mode 100644
index 0000000..83b91ca
--- /dev/null
+++ b/skills/propulsion/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: propulsion
+# prettier-ignore
+description: Manage software-work request routing into Propulsion before any downstream stage is entered. Use when starting a session with software work.
+---
+
+# Propulsion
+
+Route software-work requests into the right Propulsion entry stage before any other action.
+
+<SUBAGENT_STOP>
+If you were dispatched as a subagent to execute a specific task, SKIP THIS SKILL.
+</SUBAGENT_STOP>
+
+<EXTREMELY_IMPORTANT>
+ONCE YOU ARE FOLLOWING PROPULSION WORKFLOW, DO NOT LEAVE IT UNTIL COMPLETION. DO NOT SKIP STEPS. FOLLOW THE RULES OF EACH SKILL.
+</EXTREMELY_IMPORTANT>
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Determine whether the request is software work before clarifying questions, repo scans, external actions, or downstream Propulsion stages.
+2. If it is not software work, ignore Propulsion and respond normally.
+3. If it is a concrete failure, emit `Propulsion workflow enabled, routing to debug...`, then load and follow `debug` skill.
+4. If it is feature or product-scope work, emit `Propulsion workflow enabled, routing to brainstorm...`, then load and follow `brainstorm` skill.
+5. Stop routing. The loaded Propulsion skill now owns the workflow stage.
+
+## Rules
+
+These rules are MANDATORY.
+
+- User instructions, repository rules, and `AGENTS.md` take priority, then Propulsion skills, then default system behaviour.
+- Concrete failures route to `debug`: bug reports, regressions, failing tests, failing builds, runtime errors, crashes, broken behaviour, and diagnosis requests.
+- Feature and product-scope work routes to `brainstorm`: new features, unclear scope, UX/product shaping, requirements discovery, PRDs, and broad implementation requests.
+- If `propulsion` applies, route first. Do NOT reload `propulsion` or skip it because the task looks small, obvious, or familiar.
+- Once following Propulsion workflow, DO NOT leave it until completion. ALWAYS follow the rules of each skill.
+- ALWAYS route first. DO NOT rationalise skipping with thoughts like: "I need more context first", "I'll inspect the repo first", "This is too small for Propulsion". They are all FALSE.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Determined whether the request is software work.
+- [ ] Kept non-software-work chat outside Propulsion.
+- [ ] Routed concrete failures to `debug`.
+- [ ] Routed feature and product-scope work to `brainstorm`.
+- [ ] Emitted the route-specific required response before any other user-visible text.
+- [ ] Loaded the chosen skill immediately.
+
+## References
+
+Use these references when you need detail.
diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md
new file mode 100644
index 0000000..6d48705
--- /dev/null
+++ b/skills/review/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: review
+description: Review PRs and ref ranges with senior-level findings, validation, and exact reports. Use when reviewing PRs or base...head changes.
+---
+
+# Review
+
+Review a PR or ref range like a senior engineer and return a validated report.
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- If review scope is unclear, STOP. Ask for a PR number, PR URL, or `base...head` ref range.
+- GitHub CLI `gh` is installed and authenticated when reviewing a PR number or PR URL.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Resolve review scope and allowed context with [references/mode-selection.md](references/mode-selection.md). Stop and ask for a PR number, PR URL, or `base...head` when scope is unclear.
+2. Dispatch fresh reviewer subagents in parallel with [references/reviewer-prompt.md](references/reviewer-prompt.md). Cover the axes in [references/review-axes.md](references/review-axes.md).
+3. Dispatch fresh validator subagents with [references/validator-prompt.md](references/validator-prompt.md). Discard anything unconfirmed.
+4. Produce the final report exactly as defined in [references/report-format.md](references/report-format.md). Use only `approve`, `approve-with-comments`, `request-changes`, or `needs-clarification`.
+
+## Rules
+
+These rules are MANDATORY.
+
+- MUST accept only `#<pr-number>`, PR URLs, or `base...head`.
+- MUST require installed and authenticated `gh` only for PR review scopes.
+- ALWAYS validate both refs before reviewing `base...head`; do not guess missing refs.
+- ALWAYS use merge-base diff semantics for `base...head`.
+- ALWAYS use a severity-first model: `critical`, `high`, `medium`, `low`, `nitpick`, `question`.
+- ALWAYS report only validated findings or validated missing-context questions with concrete evidence and exact `file:line` refs when code is involved.
+- DO keep findings issue-focused. DO NOT add a positive-notes section.
+- DO NOT keep style nits, speculative risks, weak evidence, pre-existing issues, or linter-catch comments.
+- DO treat blocking findings as validated `critical` and `high` findings that would materially harm production, security, UX, or maintenance if shipped.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Scope was resolved as a PR number, PR URL, or `base...head`.
+- [ ] PR scopes used GitHub PR metadata, or range scopes validated both refs and reviewed the merge-base diff.
+- [ ] Reviewer and validator passes completed before the final report.
+- [ ] Final response matches [references/report-format.md](references/report-format.md).
+
+## References
+
+Use these references when you need detail.
+
+- [references/mode-selection.md](references/mode-selection.md) - Scope parsing, validation, and allowed context.
+- [references/review-axes.md](references/review-axes.md) - Parallel reviewer-pass contracts.
+- [references/reviewer-prompt.md](references/reviewer-prompt.md) - Prompt template for one reviewer pass.
+- [references/issue-schema.md](references/issue-schema.md) - Candidate finding and question schema.
+- [references/validator-prompt.md](references/validator-prompt.md) - Prompt template for one validator pass.
+- [references/validation-rubric.md](references/validation-rubric.md) - Disprove-first validation rules.
+- [references/report-format.md](references/report-format.md) - Exact final report shape and decision rules.
diff --git a/additional/skills/code-review/references/issue-schema.md b/skills/review/references/issue-schema.md
similarity index 97%
rename from additional/skills/code-review/references/issue-schema.md
rename to skills/review/references/issue-schema.md
index de3eb35..fa5e624 100644
--- a/additional/skills/code-review/references/issue-schema.md
+++ b/skills/review/references/issue-schema.md
@@ -46,7 +46,7 @@ Use this reference when normalising candidate findings and questions before vali
Use `(kind, file, line, severity, category, normalised summary)`.
-Only one final finding and one final inline comment per dedupe key.
+Only one final finding per dedupe key.
## Rules
diff --git a/skills/review/references/mode-selection.md b/skills/review/references/mode-selection.md
new file mode 100644
index 0000000..84bc41c
--- /dev/null
+++ b/skills/review/references/mode-selection.md
@@ -0,0 +1,40 @@
+# Mode Selection
+
+Use this reference when resolving review scope.
+
+## Accepted Forms
+
+- `#<pr-number>`
+- PR URL
+- `base...head`
+
+No other scope forms are supported.
+
+## PR Scope
+
+- Confirm explicit PR numbers match `#<number>`.
+- Accept GitHub PR URLs as explicit PR scope.
+- Require `gh` installed, authenticated, and able to access the repository only for PR scopes.
+- Resolve PR scope with `gh pr view <number-or-url> --json number,title,body,baseRefName,headRefName,headRefOid,baseRefOid,files,url`.
+- Use GitHub PR metadata for base ref, head ref, changed files, title, body, and linked artefact discovery.
+- If PR lookup fails, ask one corrective follow-up for a valid PR number or URL instead of guessing another PR.
+
+## Range Scope
+
+- Confirm range input contains exactly one `...` separator with non-empty `base` and `head` refs.
+- Validate both refs with `git rev-parse --verify <ref>^{commit}` before reviewing.
+- If either ref is missing or invalid, ask one corrective follow-up for a valid `base...head` range; do not substitute another ref.
+- Review the merge-base diff for the exact range, equivalent to `git diff <base>...<head>`.
+- Use changed files from the exact merge-base diff.
+- Use explicit user-stated review goals when intent context is needed.
+
+## Validation Checks
+
+- If scope is missing or unclear, ask the user for a PR number, PR URL, or `base...head` before review begins.
+- If the resolved scope has no reviewable file changes, still return the standard review report and state that the scope was empty.
+
+## Rules
+
+- DO accept only the documented scope forms.
+- DO NOT infer scope from the current checkout.
+- DO NOT require GitHub CLI for `base...head` range review.
diff --git a/additional/skills/code-review/references/report-format.md b/skills/review/references/report-format.md
similarity index 95%
rename from additional/skills/code-review/references/report-format.md
rename to skills/review/references/report-format.md
index fb7c64e..07bb2af 100644
--- a/additional/skills/code-review/references/report-format.md
+++ b/skills/review/references/report-format.md
@@ -2,14 +2,14 @@
Use this reference when producing the final review report.
-Use this exact report shape for both PR review and local fallback review.
+Use this exact report shape for both PR and `base...head` reviews.
If the resolved review scope is empty, still return this exact format.
```markdown
# Review Report
-**Scope**: <PR #123 | branch <base>...HEAD | uncommitted changes>
+**Scope**: <PR #123 | PR URL | base...head>
**Intent Summary**: <1-3 sentences describing the change goal from PR context or explicit user intent>
diff --git a/additional/skills/code-review/references/review-axes.md b/skills/review/references/review-axes.md
similarity index 94%
rename from additional/skills/code-review/references/review-axes.md
rename to skills/review/references/review-axes.md
index fffec41..3128ed3 100644
--- a/additional/skills/code-review/references/review-axes.md
+++ b/skills/review/references/review-axes.md
@@ -20,7 +20,7 @@ Use this reference when dispatching the focused reviewer passes.
- Review like a senior PR reviewer, not a lint pass.
- Improve overall code health; do not seek perfection.
-- Prefer concrete, merge-relevant issues the author would likely fix.
+- Prefer concrete, merge-relevant issues the author would fix.
- Read code in context, not only the diff hunk.
- Treat tests and trust-boundary changes as first-class review scope.
- Use exact evidence, quoted rules, and nearby precedent before broad principles.
@@ -43,7 +43,7 @@ Use this reference when dispatching the focused reviewer passes.
- The complaint is aesthetic or stylistic.
- The claim depends on hidden requirements.
-- The issue is too small for a real review comment.
+- The issue is too small for a final report finding.
- Multiple local patterns exist and no dominant precedent is clear.
- The suggestion is speculative future-proofing instead of a concrete fix for this diff.
diff --git a/additional/skills/code-review/references/reviewer-prompt.md b/skills/review/references/reviewer-prompt.md
similarity index 97%
rename from additional/skills/code-review/references/reviewer-prompt.md
rename to skills/review/references/reviewer-prompt.md
index 3be8d5e..faf2fd6 100644
--- a/additional/skills/code-review/references/reviewer-prompt.md
+++ b/skills/review/references/reviewer-prompt.md
@@ -54,6 +54,6 @@ Return `[]` when no candidates survive the reviewer pass.
- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise.
- DO return only normalised candidates.
- MUST replace the output placeholders with the exact JSON object shape from `references/issue-schema.md` before dispatching the reviewer.
-- DO NOT write final report sections, verdicts, inline comments, or fix patches.
+- DO NOT write final report sections, verdicts, or fix patches.
- DO NOT keep stylistic, speculative, or low-value complaints.
````
diff --git a/additional/skills/code-review/references/validation-rubric.md b/skills/review/references/validation-rubric.md
similarity index 95%
rename from additional/skills/code-review/references/validation-rubric.md
rename to skills/review/references/validation-rubric.md
index 03e9a5f..bc47763 100644
--- a/additional/skills/code-review/references/validation-rubric.md
+++ b/skills/review/references/validation-rubric.md
@@ -7,7 +7,7 @@ Use this reference when validating candidate findings and questions before final
1. Assume the finding is wrong.
2. Search the diff, full changed files, scoped rules/contracts, and gathered adjacent context for counter-evidence.
3. Reject if evidence is incomplete, ambiguous, pre-existing, or out of scope.
-4. Confirm only if objective evidence supports the claim and the issue is one the PR author would likely fix.
+4. Confirm only if objective evidence supports the claim and the issue is one the PR author would fix.
## Candidate types
@@ -47,7 +47,7 @@ Use this reference when validating candidate findings and questions before final
## Automatic reject conditions
- Style-only or subjective guidance without strong precedent or principle evidence.
-- Potential issues requiring context beyond the sanctioned review window (changed files, scoped rules/contracts, allowed adjacent files, and explicitly linked PR artefacts).
+- Potential issues requiring context beyond the sanctioned review window: changed files, scoped rules/contracts, allowed adjacent files, and explicitly linked PR artefacts.
- Pre-existing issues not introduced by reviewed diff.
- Linter-catch issues.
- Consistency findings when multiple equally accepted patterns exist.
diff --git a/additional/skills/code-review/references/validator-prompt.md b/skills/review/references/validator-prompt.md
similarity index 100%
rename from additional/skills/code-review/references/validator-prompt.md
rename to skills/review/references/validator-prompt.md
diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md
index 19d21a3..2340d7c 100644
--- a/skills/tdd/SKILL.md
+++ b/skills/tdd/SKILL.md
@@ -1,12 +1,12 @@
---
name: tdd
# prettier-ignore
-description: Build observable behaviour with one failing test at a time through red-green-refactor. Use when a slice changes user-facing behaviour, API contracts, or durable business logic, including bug fixes proven with regression tests.
+description: Build observable behaviour one failing test at a time. Use when a slice changes user-facing behaviour, API contracts, or durable business logic.
---
# TDD
-Default to red-green-refactor when a valuable behavioural test exists. Do not fabricate brittle tests when work cannot be proven through a public interface or stable seam.
+Use red-green-refactor when a valuable behavioural test exists.
## Prerequisites
@@ -35,6 +35,7 @@ These rules are MANDATORY.
- ONLY use `tdd` on observable user-visible behaviour or business logic changes.
- NO production code before a failing test WHEN a valuable behavioural test exists.
+- DO NOT fabricate brittle tests when work cannot be proven through a public interface or stable seam.
- ALWAYS write ONE test at a time for ONE observable behaviour.
- ENSURE the test initially fails for the EXPECTED reason before writing production code.
- ONLY write the minimal amount of code to make the test pass.
@@ -56,5 +57,7 @@ Do NOT leave this skill until ALL items are complete.
## References
+Use these references when you need detail.
+
- [references/testing-patterns.md](references/testing-patterns.md) - Testing patterns for guidance on how to write effective tests.
- [references/refactor-candidates.md](references/refactor-candidates.md) - Refactor candidates to identify good opportunities for refactor after the tests are green.
diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md
new file mode 100644
index 0000000..624a344
--- /dev/null
+++ b/skills/write-skill/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: write-skill
+description: Create or improve reusable skills with compact progressive-disclosure artefacts. Use when authoring, updating, or migrating any skill.
+---
+
+# Write Skill
+
+Create concise skills that package repeatable workflows without bloating context.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Load `interrogate` skill to gather the skill's job, concrete use cases, expected inputs, expected outputs, and trigger phrases before drafting.
+2. Choose the default output path `.agents/skills/{skill-name}/`; keep `name` equal to the directory name.
+3. Draft or update `SKILL.md` with the required shape in [assets/skill-template.md](assets/skill-template.md).
+4. Put only essential workflow in `SKILL.md`; move supporting artefacts into appropriate directories.
+5. Put reusable templates or static resources in `assets/`, executable helpers in `scripts/`, and detailed docs in `references/`.
+6. Validate the result with [scripts/validate-skill.js](scripts/validate-skill.js), then fix every blocking issue.
+
+## Rules
+
+These rules are MANDATORY.
+
+- Required authored-skill sections are title, one-line purpose, `## Instructions`, and `## References`.
+- Optional sections become REQUIRED when prerequisites, durable rules, completion gates, or next steps exist.
+- MUST use only canonical H2 sections in order; `## References` must be the final H2.
+- MUST keep `SKILL.md` compact: target about 50 body lines and never exceed 80 body lines.
+- MUST make `description` one line, triggerable, and clear about when the skill should be used.
+- MUST place artefacts directly under `assets/`, `references/`, or `scripts/` and link each from final references as `- [path](path) - text`.
+- MUST use progressive disclosure: metadata first, essential instructions second, artefacts only when needed.
+- MUST write short, direct, instructional prose: remove filler, pleasantries, hedging, and verbose phrases while preserving exact technical meaning.
+- MUST review [references/checklist.md](references/checklist.md) and run [scripts/validate-skill.js](scripts/validate-skill.js) before handoff.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Skill path and frontmatter name match.
+- [ ] Used `interrogate` skill to resolve the skill job, use cases, expected inputs, expected outputs, and trigger phrases before drafting.
+- [ ] `SKILL.md` contains only essential workflow and required sections.
+- [ ] Skill wording is concise, no-fluff, and technically precise.
+- [ ] Supporting artefacts are placed under `assets/`, `references/`, or `scripts/` by purpose.
+- [ ] Checklist review is complete with blocking issues fixed.
+- [ ] Validator has been run against the skill and all errors are fixed.
+
+## References
+
+Use these references when you need detail.
+
+- [assets/skill-template.md](assets/skill-template.md) - Section-by-section authoring template.
+- [references/checklist.md](references/checklist.md) - Skill quality and validation checklist.
+- [scripts/validate-skill.js](scripts/validate-skill.js) - Bun validator for skill metadata, body limits, and artefacts.
diff --git a/skills/write-skill/assets/skill-template.md b/skills/write-skill/assets/skill-template.md
new file mode 100644
index 0000000..f218830
--- /dev/null
+++ b/skills/write-skill/assets/skill-template.md
@@ -0,0 +1,97 @@
+# Skill Authoring Template
+
+Use this template for skills written to `.agents/skills/{skill-name}/SKILL.md` unless the user asks for another supported location.
+
+```markdown
+---
+name: {skill-name}
+description: {One-line action-oriented summary with the main use case and trigger words early}. Use when {specific trigger context}.
+---
+
+# {Skill Title}
+
+{One-line purpose: what repeatable job this skill performs.}
+
+## Prerequisites
+
+ALL prerequisites MUST be true before following this skill.
+
+- {Only include when the skill must stop, route, or require a condition before work starts.}
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. {First required action, including expected inputs when relevant.}
+2. {Next required action, including expected outputs and artefacts when relevant.}
+3. {Final action that completes the workflow.}
+
+## Rules
+
+These rules are MANDATORY.
+
+- {Durable rule that must always apply, using control words like MUST, DO NOT, NEVER, ONLY, STOP, or ALWAYS.}
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] {Observable completion check.}
+
+## Next Steps
+
+Once the completion gate is fully checked:
+
+- {Only include when the workflow must route or hand off after completion.}
+
+## References
+
+Use these references when you need detail.
+
+- [references/{file}.md](references/{file}.md) - {Specific purpose.}
+```
+
+## Section Instructions
+
+- `name`: use lowercase alphanumeric words joined by single hyphens; match the parent directory exactly.
+- `name`: keep to 64 characters or fewer.
+- `description`: keep one YAML line, action-oriented, third person, and triggerable with `Use when`, `Use for`, or `Use to`.
+- `description`: put the main use case and strongest trigger words early because crowded skill lists can shorten descriptions.
+- `description`: validator warns over 200 characters and errors over 300 characters.
+- Title: use a short human-readable H1 that matches the workflow, not necessarily the exact `name`.
+- One-line purpose: state the repeatable job and outcome in plain language.
+- H2 sections must use this canonical order and no other H2 names: `## Prerequisites`, `## Instructions`, `## Rules`, `## Completion Gate`, `## Next Steps`, `## References`.
+- `## Instructions` and `## References` are required.
+- Each included H2 must start with its template intro sentence; extra text may follow on the same line.
+- `## Instructions`: name expected inputs, outputs, and artefacts when they matter to the workflow.
+- `## Prerequisites`: optional; include only when conditions can block, redirect, or define valid use.
+- `## Rules`: optional; include when durable constraints must override improvisation; write rules with strong UPPERCASE control words like `MUST`, `DO NOT`, `NEVER`, `ONLY`, `STOP`, or `ALWAYS`.
+- `## Completion Gate`: optional; include when the agent must verify explicit end-state checks before leaving.
+- `## Next Steps`: optional; include only when a workflow handoff, routing choice, or post-completion action exists.
+- `## References` must be the final H2.
+- Reference bullets for artefacts must be exactly `- [path](path) - text`; link text must match href and the short description after the separator is required.
+- Only links in the final `## References` section count for artefact coverage.
+
+## Prose Style
+
+- Write commands, not essays: use direct verbs like Load, Check, Run, Fix, Stop, or Return.
+- Delete filler, pleasantries, hedging, and setup phrases such as just, really, basically, actually, simply, please, likely, may want to, and happy to.
+- Prefer short concrete words over verbose phrasing: use fix instead of implement a solution for, use check instead of perform validation of.
+- Keep exact technical meaning: preserve required keywords, file paths, commands, API names, error text, safety warnings, and ordering constraints.
+- Use fragments when clear, but expand any sentence where compression could hide a condition, risk, or handoff.
+
+## Artefact Placement
+
+- `assets/`: templates, starter files, static examples, images, prompts, and other resources copied or adapted into outputs.
+- `references/`: checklists, rubrics, explanations, examples, and long context that should not live in `SKILL.md`.
+- `scripts/`: executable validation, generation, migration, or inspection helpers the agent can run.
+- Prefer instructions over scripts unless deterministic behavior or external tooling is needed; scripts must be self-contained, dependency-light, and report actionable errors.
+- Place artefact files directly under `assets/`, `references/`, or `scripts/`; nested directories or nested files are not allowed.
+
+Keep `SKILL.md` around 50 body lines and under 80 body lines. Move detail here or into `references/` instead of expanding the main skill.
+
+## Validator CLI
+
+- Run as `bun scripts/validate-skill.js <skill-path>` from the skill directory, or `bun path/to/validate-skill.js <skill-path>` from elsewhere.
+- The validator requires exactly one skill directory path, not a file path.
+- The validator always writes JSON to stdout and exits non-zero when `valid` is `false`.
diff --git a/skills/write-skill/references/checklist.md b/skills/write-skill/references/checklist.md
new file mode 100644
index 0000000..85968ab
--- /dev/null
+++ b/skills/write-skill/references/checklist.md
@@ -0,0 +1,76 @@
+# Skill Checklist
+
+Use this checklist before handing off a new or updated skill.
+
+## Frontmatter
+
+- [ ] `name` is lowercase with single hyphen separators.
+- [ ] `name` is 1-64 characters.
+- [ ] `name` matches the parent directory name.
+- [ ] `name` matches `^[a-z0-9]+(-[a-z0-9]+)*$`.
+- [ ] `description` is one line only.
+- [ ] `description` is 200 characters or fewer to avoid validator warnings.
+- [ ] `description` is 300 characters or fewer to avoid validator errors.
+- [ ] `description` includes what the skill does.
+- [ ] `description` includes `Use when`, `Use for`, or `Use to`.
+- [ ] `description` front-loads the main use case and strongest trigger words because crowded skill lists can shorten descriptions.
+- [ ] `description` includes natural trigger keywords a user would say.
+- [ ] `description` is third person and action-oriented.
+- [ ] `description` starts with a strong action verb such as Create, Validate, Review, Manage, or Execute.
+
+## Artefact Layout
+
+- [ ] Repository skill path defaults to `.agents/skills/{skill-name}/SKILL.md`.
+- [ ] `SKILL.md` exists and contains required `name` and `description` frontmatter.
+- [ ] `assets/` contains only reusable templates or static resources.
+- [ ] `references/` contains detailed documentation, examples, rubrics, or checklists.
+- [ ] `scripts/` contains only executable helpers and documents how to run them.
+- [ ] Scripts are used only when deterministic behavior or external tooling is needed.
+- [ ] Scripts are self-contained, dependency-light, and report actionable errors.
+- [ ] Artefact files are directly under `assets/`, `references/`, or `scripts/`; no nested artefact directories or files exist.
+- [ ] No unnecessary README, changelog, or duplicate auxiliary files were added.
+
+## SKILL.md Body
+
+- [ ] Includes a title and one-line purpose.
+- [ ] Includes required `## Instructions` and `## References` sections.
+- [ ] Uses only allowed H2 sections: `## Prerequisites`, `## Instructions`, `## Rules`, `## Completion Gate`, `## Next Steps`, `## References`.
+- [ ] H2 sections follow the canonical order exactly when present.
+- [ ] `## References` is the final H2 section.
+- [ ] Each included H2 starts with its required intro sentence from the template; extra text may follow on the same line.
+- [ ] Includes `## Prerequisites` when the skill can be invalid, blocked, or must route elsewhere.
+- [ ] Includes `## Rules` when durable instructions must always apply.
+- [ ] Includes `## Completion Gate` when explicit finish checks are needed.
+- [ ] Includes `## Next Steps` when a handoff or post-completion route exists.
+- [ ] Uses ordered steps for workflows that must run in sequence.
+- [ ] Instructions name expected inputs, outputs, and artefacts when relevant.
+- [ ] `## Rules` uses strong control words such as `MUST`, `DO NOT`, `NEVER`, `ONLY`, `STOP`, or `ALWAYS`.
+- [ ] Body stays at or below 50 non-empty lines to avoid validator warnings.
+- [ ] Body stays at or below 80 non-empty lines to avoid validator errors.
+
+## Language Quality
+
+- [ ] Removes filler words such as just, really, basically, actually, and simply.
+- [ ] Removes pleasantries and chatty setup such as sure, certainly, happy to, and please.
+- [ ] Removes hedging when the instruction is required, including likely, maybe, should probably, and may want to.
+- [ ] Replaces verbose phrasing with short direct wording without changing the instruction.
+- [ ] Preserves explicit technical meaning: commands, paths, APIs, error text, safety warnings, conditions, and ordering constraints stay exact.
+
+## Progressive Disclosure
+
+- [ ] Level 1 metadata is enough to decide whether to load the skill.
+- [ ] Level 2 `SKILL.md` contains only essential workflow and durable rules.
+- [ ] Level 3 artefacts hold examples, templates, explanations, and long checklists.
+- [ ] All linked references resolve from `SKILL.md` using relative paths.
+- [ ] Every `assets/`, `references/`, and `scripts/` artefact is linked from the final `## References` section.
+- [ ] Reference bullets use exactly `- [path](path) - text`.
+- [ ] Reference bullet link text matches the href exactly.
+- [ ] Reference bullets include a short description after the separator in `- [path](path) - text`.
+- [ ] No orphaned reference, asset, or script files exist.
+
+## Validation
+
+- [ ] Manually verify frontmatter, line count, links, and artefact placement.
+- [ ] Run the dedicated validator with exactly one skill directory path.
+- [ ] Do not pass validator options or a file path.
+- [ ] Read validator output as JSON on both success and failure.
diff --git a/skills/write-skill/scripts/validate-skill.js b/skills/write-skill/scripts/validate-skill.js
new file mode 100644
index 0000000..7aa5fd3
--- /dev/null
+++ b/skills/write-skill/scripts/validate-skill.js
@@ -0,0 +1,426 @@
+#!/usr/bin/env bun
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+const errors = [];
+const warnings = [];
+const allowedSections = [
+ 'Prerequisites',
+ 'Instructions',
+ 'Rules',
+ 'Completion Gate',
+ 'Next Steps',
+ 'References',
+];
+const sectionIntroLines = {
+ Prerequisites:
+ 'ALL prerequisites MUST be true before following this skill.',
+ Instructions: 'Follow these steps IN ORDER. Do NOT skip steps.',
+ Rules: 'These rules are MANDATORY.',
+ 'Completion Gate': 'Do NOT leave this skill until ALL items are complete.',
+ 'Next Steps': 'Once the completion gate is fully checked:',
+ References: 'Use these references when you need detail.',
+};
+
+function addError(message) {
+ errors.push(message);
+}
+
+function addWarning(message) {
+ warnings.push(message);
+}
+
+function report(path, stats = null) {
+ return {
+ path,
+ valid: errors.length === 0,
+ errors,
+ warnings,
+ stats,
+ };
+}
+
+function parseFrontmatter(content) {
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+ if (!match) {
+ addError(
+ 'Add YAML frontmatter with name and description at the top of SKILL.md.',
+ );
+ return { name: null, description: null, body: content, raw: '' };
+ }
+
+ const raw = match[1];
+ const name = raw.match(/^name:\s*(.+)$/m)?.[1]?.trim() || null;
+ const description = readDescription(raw);
+
+ return { name, description, body: content.slice(match[0].length), raw };
+}
+
+function readDescription(raw) {
+ const lines = raw.split(/\r?\n/);
+ const index = lines.findIndex((line) => line.startsWith('description:'));
+ if (index === -1) return null;
+
+ const firstValue = lines[index].replace(/^description:\s*/, '').trim();
+ if (firstValue === '|' || firstValue === '>') {
+ return lines
+ .slice(index + 1)
+ .filter((line) => /^\s+\S/.test(line))
+ .map((line) => line.trim())
+ .join(' ');
+ }
+
+ return firstValue || null;
+}
+
+function hasMultilineDescription(raw) {
+ const lines = raw.split(/\r?\n/);
+ const index = lines.findIndex((line) => line.startsWith('description:'));
+ if (index === -1) return false;
+ const firstValue = lines[index].replace(/^description:\s*/, '').trim();
+ if (firstValue === '|' || firstValue === '>') return true;
+
+ return lines.slice(index + 1).some((line) => /^\s+\S/.test(line));
+}
+
+function validateName(name, dirName) {
+ if (!name) {
+ addError(
+ 'Add frontmatter name and set it to the skill directory name.',
+ );
+ return;
+ }
+ if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+ addError(
+ `Fix frontmatter name "${name}" to match ^[a-z0-9]+(-[a-z0-9]+)*$.`,
+ );
+ }
+ if (name.length > 64) {
+ addError(
+ `Shorten frontmatter name "${name}" to 64 characters or fewer.`,
+ );
+ }
+ if (name !== dirName) {
+ addError(
+ `Set frontmatter name to "${dirName}" so it matches the skill directory.`,
+ );
+ }
+}
+
+function validateDescription(description, raw) {
+ if (!description) {
+ addError(
+ 'Add a one-line frontmatter description with Use when, Use for, or Use to.',
+ );
+ return;
+ }
+ if (hasMultilineDescription(raw)) {
+ addError('Rewrite frontmatter description as a single YAML line.');
+ }
+ if (description.length > 300) {
+ addError(
+ `Shorten description to 300 characters or fewer. Current length: ${description.length}.`,
+ );
+ } else if (description.length > 200) {
+ addWarning(
+ `Shorten description to 200 characters or fewer for easier skill selection. Current length: ${description.length}.`,
+ );
+ }
+ if (!/\bUse (when|for|to)\b/.test(description)) {
+ addError(
+ 'Add Use when, Use for, or Use to to the one-line description so agents know when to load the skill.',
+ );
+ }
+ if (/\b(I|me|my|mine|we|us|our|ours)\b/i.test(description)) {
+ addWarning(
+ 'Rewrite description in third person; avoid first-person wording like I, me, my, we, or our.',
+ );
+ }
+ if (
+ !/^(Create|Build|Design|Analyze|Test|Validate|Generate|Process|Manage|Execute|Handle|Provide|Review|Write|Author|Migrate|Improve|Add|Update|Check)\b/.test(
+ description,
+ )
+ ) {
+ addWarning(
+ 'Start description with a strong action verb such as Create, Validate, Review, Manage, or Execute.',
+ );
+ }
+}
+
+function validateBody(body) {
+ const lines = body.split(/\r?\n/);
+ const nonEmpty = lines
+ .map((line, index) => ({ line: line.trim(), index }))
+ .filter(({ line }) => line);
+ const bodyLines = nonEmpty.length;
+
+ if (bodyLines > 80) {
+ addError(
+ `Move detail out of SKILL.md; body has ${bodyLines} non-empty lines and must stay at or below 80.`,
+ );
+ } else if (bodyLines > 50) {
+ addWarning(
+ `Move detail out of SKILL.md; body has ${bodyLines} non-empty lines and should stay at or below 50.`,
+ );
+ }
+
+ const first = nonEmpty[0];
+ if (!first || !/^#\s+\S/.test(first.line)) {
+ addError(
+ 'Make the first non-empty body line an H1 title, for example: # Skill Name.',
+ );
+ }
+
+ const firstH2Index = lines.findIndex((line) =>
+ /^##\s+\S/.test(line.trim()),
+ );
+ const titleIndex = first?.index ?? -1;
+ const purpose = lines
+ .slice(
+ titleIndex + 1,
+ firstH2Index === -1 ? lines.length : firstH2Index,
+ )
+ .map((line) => line.trim())
+ .find((line) => line);
+ if (!purpose || purpose.startsWith('#')) {
+ addError(
+ 'Add one non-empty, non-heading purpose line immediately after the H1 title and before the first H2.',
+ );
+ }
+
+ const h2Sections = nonEmpty
+ .filter(({ line }) => /^##\s+\S/.test(line))
+ .map(({ line, index }) => ({
+ title: line.replace(/^##\s+/, '').trim(),
+ index,
+ }));
+ validateSections(h2Sections, lines);
+
+ return { bodyLines, h2Sections: h2Sections.length };
+}
+
+function validateSections(h2Sections, lines) {
+ const titles = h2Sections.map(({ title }) => title);
+ for (const required of ['Instructions', 'References']) {
+ if (!titles.includes(required))
+ addError(`Add required section ## ${required}.`);
+ }
+
+ let lastAllowedIndex = -1;
+ for (const title of titles) {
+ const allowedIndex = allowedSections.indexOf(title);
+ if (allowedIndex === -1) {
+ addError(
+ `Remove unsupported H2 section ## ${title}. Allowed H2 sections are ${allowedSections.map((section) => `## ${section}`).join(', ')}.`,
+ );
+ continue;
+ }
+ if (allowedIndex < lastAllowedIndex) {
+ addError(
+ `Move ## ${title} before ## ${allowedSections[lastAllowedIndex]} to match the canonical section order.`,
+ );
+ } else {
+ lastAllowedIndex = allowedIndex;
+ }
+ }
+
+ const final = titles[titles.length - 1];
+ if (titles.includes('References') && final !== 'References') {
+ addError('Move ## References to the final H2 section.');
+ }
+
+ for (let index = 0; index < h2Sections.length; index++) {
+ const { title, index: lineIndex } = h2Sections[index];
+ const requiredIntro = sectionIntroLines[title];
+ if (!requiredIntro) continue;
+
+ const nextSectionIndex = h2Sections[index + 1]?.index ?? lines.length;
+ const firstContentLine = lines
+ .slice(lineIndex + 1, nextSectionIndex)
+ .map((line) => line.trim())
+ .find((line) => line);
+
+ if (!firstContentLine?.startsWith(requiredIntro)) {
+ addError(`Start ## ${title} with: ${requiredIntro}`);
+ }
+ }
+}
+
+function collectArtifacts(skillPath) {
+ const artifacts = [];
+ for (const dir of ['assets', 'references', 'scripts']) {
+ const dirPath = join(skillPath, dir);
+ if (!existsSync(dirPath)) continue;
+
+ for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+ const artifactPath = `${dir}/${entry.name}`;
+ if (entry.isFile()) {
+ artifacts.push(artifactPath);
+ continue;
+ }
+ if (entry.isDirectory()) {
+ for (const nested of collectNestedFiles(
+ join(dirPath, entry.name),
+ artifactPath,
+ )) {
+ addError(
+ `Move nested artifact ${nested} directly under ${dir}/; nested artifact files are not allowed.`,
+ );
+ }
+ }
+ }
+ }
+ return artifacts;
+}
+
+function collectNestedFiles(dirPath, prefix) {
+ const files = [];
+ for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+ const nestedPath = `${prefix}/${entry.name}`;
+ if (entry.isFile()) files.push(nestedPath);
+ if (entry.isDirectory())
+ files.push(
+ ...collectNestedFiles(join(dirPath, entry.name), nestedPath),
+ );
+ }
+ return files;
+}
+
+function finalReferencesSection(body) {
+ const lines = body.split(/\r?\n/);
+ const start = lines.findIndex((line) => line.trim() === '## References');
+ if (start === -1) return '';
+
+ const rest = lines.slice(start + 1);
+ const nextH2 = rest.findIndex((line) => /^##\s+\S/.test(line.trim()));
+ return (nextH2 === -1 ? rest : rest.slice(0, nextH2)).join('\n');
+}
+
+function validateArtifacts(skillPath, body) {
+ const artifacts = collectArtifacts(skillPath);
+ const linked = new Set();
+ const references = finalReferencesSection(body);
+ const artifactLink =
+ /\[(assets|references|scripts)\/[^\]]+\]\((assets|references|scripts)\/[^)]+\)/;
+
+ for (const rawLine of references.split(/\r?\n/)) {
+ const line = rawLine.trimStart();
+ if (!artifactLink.test(line)) continue;
+
+ const match = line.match(
+ /^- \[((?:assets|references|scripts)\/[^\]]+)\]\(((?:assets|references|scripts)\/[^)]+)\) - (.*)$/,
+ );
+ const emptyDescriptionMatch = line.match(
+ /^- \[((?:assets|references|scripts)\/[^\]]+)\]\(((?:assets|references|scripts)\/[^)]+)\) -\s*$/,
+ );
+ const text = match?.[1];
+ const href = match?.[2];
+ const description = match?.[3]?.trim();
+ const path = href ?? text;
+
+ if (
+ !match &&
+ emptyDescriptionMatch?.[1] === emptyDescriptionMatch?.[2]
+ ) {
+ linked.add(emptyDescriptionMatch[2]);
+ addError(
+ `Add a short description after " - " for artifact reference ${emptyDescriptionMatch[2]}.`,
+ );
+ if (!existsSync(join(skillPath, emptyDescriptionMatch[2]))) {
+ addError(
+ `Create linked artifact ${emptyDescriptionMatch[2]} or remove its References bullet.`,
+ );
+ }
+ continue;
+ }
+
+ if (!match || text !== href) {
+ const expected = text ?? path ?? 'artifact/path';
+ addError(
+ `Reference artifact ${expected} with matching text and href: - [${expected}](${expected}) - short description.`,
+ );
+ continue;
+ }
+
+ linked.add(href);
+ if (!description) {
+ addError(
+ `Add a short description after " - " for artifact reference ${href}.`,
+ );
+ }
+ if (!existsSync(join(skillPath, href))) {
+ addError(
+ `Create linked artifact ${href} or remove its References bullet.`,
+ );
+ }
+ }
+
+ for (const artifact of artifacts) {
+ if (!linked.has(artifact)) {
+ addError(
+ `Link artifact ${artifact} from the final ## References section.`,
+ );
+ }
+ }
+
+ return artifacts.length;
+}
+
+function validateSkill(skillPath) {
+ if (!existsSync(skillPath)) {
+ addError(
+ `Create the skill directory or fix the path; not found: ${skillPath}`,
+ );
+ return null;
+ }
+ if (!statSync(skillPath).isDirectory()) {
+ addError(`Provide a skill directory, not a file: ${skillPath}`);
+ return null;
+ }
+
+ const skillMdPath = join(skillPath, 'SKILL.md');
+ if (!existsSync(skillMdPath)) {
+ addError('Add SKILL.md to the skill directory.');
+ return null;
+ }
+
+ const content = readFileSync(skillMdPath, 'utf8');
+ const { name, description, body, raw } = parseFrontmatter(content);
+ validateName(name, basename(skillPath));
+ validateDescription(description, raw);
+ const bodyStats = validateBody(body);
+ const artifacts = validateArtifacts(skillPath, body);
+
+ return { ...bodyStats, artifacts };
+}
+
+let targetArg = null;
+for (const arg of args) {
+ if (arg.startsWith('--')) {
+ addError(
+ `Unsupported option ${arg}. Provide only a skill directory path.`,
+ );
+ } else if (targetArg) {
+ addError('Provide only one skill directory path.');
+ } else {
+ targetArg = arg;
+ }
+}
+
+if (!targetArg && errors.length === 0) {
+ addError(
+ 'Provide a skill directory path: bun validate-skill.js <skill-path>',
+ );
+}
+
+const targetPath = targetArg ? resolve(targetArg) : null;
+const stats =
+ targetPath && errors.length === 0 ? validateSkill(targetPath) : null;
+const displayPath = targetPath
+ ? relative(process.cwd(), targetPath) || targetPath
+ : null;
+const output = report(displayPath, stats);
+
+console.log(JSON.stringify(output, null, 2));
+process.exit(output.valid ? 0 : 1);
diff --git a/tests/codex-hook.test.js b/tests/codex-hook.test.js
new file mode 100644
index 0000000..09d74b8
--- /dev/null
+++ b/tests/codex-hook.test.js
@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'bun:test';
+import { readFile } from 'node:fs/promises';
+
+import {
+ PROPULSION_BOOTSTRAP_GUIDANCE,
+ getPropulsionBootstrapGuidance,
+} from '../lib/bootstrap-guidance.js';
+
+async function readJson(path) {
+ return JSON.parse(await readFile(path, 'utf8'));
+}
+
+describe('Codex Propulsion bootstrap guidance', () => {
+ test('uses the shared Propulsion bootstrap contract', () => {
+ expect(getPropulsionBootstrapGuidance()).toBe(
+ PROPULSION_BOOTSTRAP_GUIDANCE,
+ );
+ });
+
+ test('registers a compact plugin-local session-start hook matcher', async () => {
+ const config = await readJson('hooks/hooks.json');
+
+ expect(config.hooks.SessionStart).toEqual([
+ {
+ matcher: 'startup|clear|compact|resume',
+ hooks: [
+ {
+ type: 'command',
+ command: './hooks/run-hook.cmd session-start',
+ },
+ ],
+ },
+ ]);
+ });
+
+ test('prints Codex SessionStart additional context as parseable JSON', async () => {
+ const result = Bun.spawnSync({
+ cmd: ['./hooks/run-hook.cmd', 'session-start'],
+ stdout: 'pipe',
+ stderr: 'pipe',
+ });
+
+ expect(result.exitCode).toBe(0);
+
+ const output = new TextDecoder().decode(result.stdout).trim();
+ const payload = JSON.parse(output);
+
+ expect(payload).toEqual({
+ hookSpecificOutput: {
+ hookEventName: 'SessionStart',
+ additionalContext: PROPULSION_BOOTSTRAP_GUIDANCE,
+ },
+ });
+ expect(payload.hookSpecificOutput.additionalContext).toContain(
+ '<EXTREMELY_IMPORTANT>',
+ );
+ expect(payload.hookSpecificOutput.additionalContext).toContain(
+ 'Propulsion workflow entry point: load and follow the propulsion skill when the request is software work.',
+ );
+ expect(payload.hookSpecificOutput.additionalContext).toContain(
+ 'Route software work through Propulsion before downstream stages.',
+ );
+ });
+});
diff --git a/tests/opencode-plugin.test.js b/tests/opencode-plugin.test.js
new file mode 100644
index 0000000..a76c886
--- /dev/null
+++ b/tests/opencode-plugin.test.js
@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'bun:test';
+import { readFile } from 'node:fs/promises';
+
+import { getPropulsionBootstrapGuidance } from '../lib/bootstrap-guidance.js';
+
+describe('OpenCode Propulsion bootstrap guidance', () => {
+ test('exposes the root package entry for OpenCode package loading', async () => {
+ const manifest = JSON.parse(await readFile('package.json', 'utf8'));
+ const rootExports = await import('../index.mjs');
+
+ expect(manifest.main).toBe('./index.mjs');
+ expect(manifest.exports).toBe('./index.mjs');
+ expect(
+ Object.values(rootExports).every(
+ (value) =>
+ typeof value === 'function' ||
+ (typeof value === 'object' &&
+ value !== null &&
+ typeof value.server === 'function'),
+ ),
+ ).toBe(true);
+ });
+
+ test('provides high-priority Propulsion routing guidance', () => {
+ const guidance = getPropulsionBootstrapGuidance();
+
+ expect(guidance).toContain('<EXTREMELY_IMPORTANT>');
+ expect(guidance).toContain('</EXTREMELY_IMPORTANT>');
+ expect(guidance).toContain('propulsion');
+ expect(guidance).toContain(
+ 'Route software work through Propulsion before downstream stages.',
+ );
+ expect(guidance).toContain(
+ 'Route software-work requests into the right Propulsion entry stage before any other action.',
+ );
+ });
+
+ test('registers an OpenCode messages transform that prepends Propulsion guidance', async () => {
+ const pluginPackage = (await import('../index.mjs')).default;
+ const PropulsionPlugin = pluginPackage.server;
+ const hooks = await PropulsionPlugin({});
+ const output = {
+ system: ['existing system prompt'],
+ messages: [{ role: 'user', content: 'Build the thing' }],
+ };
+
+ expect(hooks).toEqual(
+ expect.objectContaining({
+ 'experimental.chat.messages.transform': expect.any(Function),
+ }),
+ );
+ expect(hooks).not.toHaveProperty('experimental.chat.system.transform');
+
+ await hooks['experimental.chat.messages.transform']({}, output);
+
+ expect(output.system).toEqual(['existing system prompt']);
+ expect(output.messages).toEqual([
+ {
+ role: 'system',
+ content: getPropulsionBootstrapGuidance(),
+ },
+ { role: 'user', content: 'Build the thing' },
+ ]);
+ });
+});
diff --git a/tests/opencode/run-tests.sh b/tests/opencode/run-tests.sh
deleted file mode 100644
index b8f0aeb..0000000
--- a/tests/opencode/run-tests.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-
-tests=(
- "test-skill-loading.sh"
-)
-
-for test_file in "${tests[@]}"; do
- echo "Running $test_file"
- (
- cd "$SCRIPT_DIR"
- bash "./$test_file"
- )
-done
-
-echo "OpenCode smoke tests passed"
diff --git a/tests/opencode/test-skill-loading.sh b/tests/opencode/test-skill-loading.sh
deleted file mode 100644
index fed8c6a..0000000
--- a/tests/opencode/test-skill-loading.sh
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-
-skills_output="$(mktemp)"
-pure_output="$(mktemp)"
-config_home="$(mktemp -d)"
-trap 'rm -f "$skills_output" "$pure_output"; rm -rf "$config_home"' EXIT
-
-cd "$REPO_ROOT"
-workflow_skill='"name": "propulsion-workflow"'
-workflow_path="$REPO_ROOT/skills/propulsion-workflow/SKILL.md"
-
-XDG_CONFIG_HOME="$config_home" opencode debug skill >"$skills_output" 2>&1
-XDG_CONFIG_HOME="$config_home" opencode debug skill --pure >"$pure_output" 2>&1
-
-if ! /usr/bin/grep -F -a -q "$workflow_skill" "$skills_output"; then
- echo "Expected propulsion-workflow skill in plugin-backed skill list"
- exit 1
-fi
-
-if ! /usr/bin/grep -F -a -q "$workflow_path" "$skills_output"; then
- echo "Expected propulsion-workflow skill path in plugin-backed skill list"
- exit 1
-fi
-
-if /usr/bin/grep -F -a -q "$workflow_skill" "$pure_output"; then
- echo "Pure skill listing should not expose propulsion-workflow"
- exit 1
-fi
diff --git a/tests/propulsion-plugin.test.js b/tests/propulsion-plugin.test.js
deleted file mode 100644
index 55d1c2c..0000000
--- a/tests/propulsion-plugin.test.js
+++ /dev/null
@@ -1,192 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { PropulsionPlugin } from '../.opencode/plugins/propulsion.js';
-
-const dirname = path.dirname(fileURLToPath(import.meta.url));
-const repoRoot = path.resolve(dirname, '..');
-const skillsDir = path.join(repoRoot, 'skills');
-const additionalSkillsDir = path.join(repoRoot, 'additional/skills');
-
-const createTransformOutput = () => ({
- messages: [
- {
- info: {
- id: 'msg_user_1',
- sessionID: 'ses_1',
- role: 'user',
- },
- parts: [
- {
- id: 'prt_user_1',
- sessionID: 'ses_1',
- messageID: 'msg_user_1',
- type: 'text',
- text: 'hello',
- },
- ],
- },
- ],
-});
-
-describe('PropulsionPlugin config', () => {
- test('adds the bundled skills path once', async () => {
- const hooks = await PropulsionPlugin({});
- const config = {
- skills: {
- paths: [skillsDir],
- },
- };
-
- await hooks.config?.(config);
-
- expect(config.skills.paths).toEqual([skillsDir]);
- });
-
- test('preserves user commands while merging additional defaults', async () => {
- const hooks = await PropulsionPlugin({}, { additional: true });
- const config = {
- command: {
- commit: {
- template: 'user override',
- description: 'local command wins',
- },
- },
- };
-
- await hooks.config?.(config);
-
- expect(config.skills.paths).toContain(skillsDir);
- expect(config.skills.paths).toContain(additionalSkillsDir);
- expect(config.command.commit).toEqual({
- template: 'user override',
- description: 'local command wins',
- });
- expect(config.command.pr.description).toContain('pull request');
- expect(config.command.init.template).toContain('agentic-config');
- });
-});
-
-describe('PropulsionPlugin transform', () => {
- test('injects the propulsion-workflow bootstrap into the first user message', async () => {
- const hooks = await PropulsionPlugin({});
- const output = createTransformOutput();
-
- await hooks['experimental.chat.messages.transform']?.({}, output);
-
- expect(output.messages[0]?.parts).toHaveLength(2);
- expect(output.messages[0]?.parts[0]).toMatchObject({
- type: 'text',
- sessionID: 'ses_1',
- messageID: 'msg_user_1',
- });
- expect(output.messages[0]?.parts[0].text).toContain(
- 'You are using the Propulsion workflow.',
- );
- expect(output.messages[0]?.parts[0].text).toContain(
- 'Do NOT use the skill tool to load "propulsion-workflow" again',
- );
- });
-
- test('does not inject the bootstrap twice', async () => {
- const hooks = await PropulsionPlugin({});
- const output = createTransformOutput();
-
- await hooks['experimental.chat.messages.transform']?.({}, output);
- await hooks['experimental.chat.messages.transform']?.({}, output);
-
- expect(
- output.messages[0]?.parts.filter(
- (part) =>
- part.type === 'text' &&
- part.text.includes(
- 'You are using the Propulsion workflow.',
- ),
- ),
- ).toHaveLength(1);
- });
-});
-
-describe('published package contract', () => {
- test('imports from node_modules under plain Node after npm pack', () => {
- const tempRoot = fs.mkdtempSync(
- path.join(os.tmpdir(), 'propulsion-plugin-test-'),
- );
- const packDir = path.join(tempRoot, 'pack');
-
- try {
- fs.mkdirSync(packDir);
-
- const tarballName = execFileSync(
- 'npm',
- ['pack', '--quiet', '--pack-destination', packDir],
- {
- cwd: repoRoot,
- encoding: 'utf8',
- },
- ).trim();
- const tarballPath = path.join(packDir, tarballName);
- const appDir = path.join(tempRoot, 'app');
-
- fs.mkdirSync(appDir);
-
- execFileSync('npm', ['init', '-y'], {
- cwd: appDir,
- stdio: 'ignore',
- });
- execFileSync('npm', ['install', tarballPath], {
- cwd: appDir,
- stdio: 'ignore',
- });
-
- const output = execFileSync(
- 'node',
- [
- '--input-type=module',
- '-e',
- "import('propulsion').then(() => console.log('IMPORT_OK'))",
- ],
- {
- cwd: appDir,
- encoding: 'utf8',
- },
- );
-
- expect(output).toContain('IMPORT_OK');
- } finally {
- fs.rmSync(tempRoot, { recursive: true, force: true });
- }
- }, 30000);
-
- test('opencode smoke test ignores ambient global config', () => {
- const tempRoot = fs.mkdtempSync(
- path.join(os.tmpdir(), 'propulsion-opencode-config-test-'),
- );
-
- try {
- const configDir = path.join(tempRoot, 'config', 'opencode');
- fs.mkdirSync(configDir, { recursive: true });
- fs.writeFileSync(
- path.join(configDir, 'opencode.json'),
- '{ invalid json\n',
- );
-
- expect(() =>
- execFileSync('bash', ['tests/opencode/test-skill-loading.sh'], {
- cwd: repoRoot,
- env: {
- ...process.env,
- XDG_CONFIG_HOME: path.join(tempRoot, 'config'),
- },
- stdio: 'pipe',
- }),
- ).not.toThrow();
- } finally {
- fs.rmSync(tempRoot, { recursive: true, force: true });
- }
- }, 30000);
-});
diff --git a/tests/write-skill-validator.test.js b/tests/write-skill-validator.test.js
new file mode 100644
index 0000000..1b91dce
--- /dev/null
+++ b/tests/write-skill-validator.test.js
@@ -0,0 +1,513 @@
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const repoRoot = join(import.meta.dir, '..');
+const validatorPath = join(
+ repoRoot,
+ 'skills/write-skill/scripts/validate-skill.js',
+);
+const shippedSkillsPath = join(repoRoot, 'skills');
+
+function runValidator(args = []) {
+ const result = spawnSync('bun', [validatorPath, ...args], {
+ cwd: repoRoot,
+ encoding: 'utf8',
+ });
+
+ return {
+ ...result,
+ report: JSON.parse(result.stdout),
+ };
+}
+
+function shippedSkillPaths() {
+ return readdirSync(shippedSkillsPath, { withFileTypes: true })
+ .filter((entry) => entry.isDirectory())
+ .map((entry) => `skills/${entry.name}`)
+ .toSorted();
+}
+
+function validatorOutput(result) {
+ const details = [];
+
+ if (result.stdout.trim()) {
+ details.push(`stdout:\n${result.stdout.trim()}`);
+ }
+
+ if (result.stderr.trim()) {
+ details.push(`stderr:\n${result.stderr.trim()}`);
+ }
+
+ return details.join('\n\n') || 'Validator produced no stdout or stderr.';
+}
+
+function validSkillMd(overrides = {}) {
+ const name = overrides.name ?? 'good-skill';
+ const description =
+ overrides.description ??
+ 'Validate reusable workflow skills. Use when checking authored skill structure.';
+ const sections =
+ overrides.sections ??
+ `## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Validate the skill.
+
+## References
+
+Use these references when you need detail.
+`;
+
+ return `---
+name: ${name}
+description: ${description}
+---
+
+# ${overrides.title ?? 'Good Skill'}
+
+${overrides.purpose ?? 'Validate reusable skill structure before handoff.'}
+
+${sections}`;
+}
+
+function createSkill(name, skillMd = validSkillMd({ name }), files = {}) {
+ const root = mkdtempSync(join(tmpdir(), 'writing-skill-validator-'));
+ const skillPath = join(root, name);
+ mkdirSync(skillPath);
+ writeFileSync(join(skillPath, 'SKILL.md'), skillMd);
+
+ for (const [filePath, content] of Object.entries(files)) {
+ const parts = filePath.split('/');
+ parts.pop();
+ if (parts.length > 0) {
+ mkdirSync(join(skillPath, ...parts), { recursive: true });
+ }
+ writeFileSync(join(skillPath, filePath), content);
+ }
+
+ return skillPath;
+}
+
+describe('write-skill validator', () => {
+ test('ships a standalone JavaScript validator', () => {
+ expect(existsSync(validatorPath)).toBe(true);
+ });
+
+ test('requires a skill path and always outputs JSON', () => {
+ const result = runValidator();
+
+ expect(result.status).toBe(1);
+ expect(result.report).toMatchObject({
+ path: null,
+ valid: false,
+ warnings: [],
+ stats: null,
+ });
+ expect(result.report.errors).toContain(
+ 'Provide a skill directory path: bun validate-skill.js <skill-path>',
+ );
+ });
+
+ test('accepts the write-skill skill as JSON', () => {
+ const result = runValidator(['skills/write-skill']);
+
+ expect(result.status).toBe(0);
+ expect(result.report.valid).toBe(true);
+ expect(result.report).toEqual({
+ path: 'skills/write-skill',
+ valid: true,
+ errors: [],
+ warnings: [],
+ stats: expect.objectContaining({
+ bodyLines: expect.any(Number),
+ artifacts: expect.any(Number),
+ }),
+ });
+ });
+
+ test('validates every shipped skill', () => {
+ const skillPaths = shippedSkillPaths();
+
+ expect(skillPaths.length).toBeGreaterThan(0);
+
+ for (const skillPath of skillPaths) {
+ const result = runValidator([skillPath]);
+
+ if (result.status !== 0) {
+ throw new Error(
+ `Validator failed for ${skillPath}.\n\n${validatorOutput(result)}`,
+ );
+ }
+ }
+ });
+
+ test('rejects unknown flags instead of supporting legacy options', () => {
+ const result = runValidator(['--unknown']);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Unsupported option --unknown. Provide only a skill directory path.',
+ );
+ });
+
+ test('validates name requirements', () => {
+ const longName = `Bad-${'x'.repeat(65)}`;
+ const skillPath = createSkill(
+ 'expected-name',
+ validSkillMd({ name: longName }),
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ `Fix frontmatter name "${longName}" to match ^[a-z0-9]+(-[a-z0-9]+)*$.`,
+ );
+ expect(result.report.errors).toContain(
+ `Shorten frontmatter name "${longName}" to 64 characters or fewer.`,
+ );
+ expect(result.report.errors).toContain(
+ 'Set frontmatter name to "expected-name" so it matches the skill directory.',
+ );
+ });
+
+ test('validates description requirements and warnings', () => {
+ const longFirstPersonDescription =
+ 'I help agents with reusable skill review language that is intentionally long enough to cross the warning threshold while still remaining under the hard maximum for metadata checks. '.padEnd(
+ 220,
+ 'x',
+ );
+ const skillPath = createSkill(
+ 'description-skill',
+ validSkillMd({
+ name: 'description-skill',
+ description: longFirstPersonDescription,
+ }),
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Add Use when, Use for, or Use to to the one-line description so agents know when to load the skill.',
+ );
+ expect(result.report.warnings).toContain(
+ 'Shorten description to 200 characters or fewer for easier skill selection. Current length: 220.',
+ );
+ expect(result.report.warnings).toContain(
+ 'Rewrite description in third person; avoid first-person wording like I, me, my, we, or our.',
+ );
+ expect(result.report.warnings).toContain(
+ 'Start description with a strong action verb such as Create, Validate, Review, Manage, or Execute.',
+ );
+ });
+
+ test('errors when description is missing', () => {
+ const skillPath = createSkill(
+ 'missing-description',
+ `---
+name: missing-description
+---
+
+# Missing Description
+
+Validate missing description metadata before handoff.
+
+## Instructions
+
+1. Validate descriptions.
+
+## References
+`,
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Add a one-line frontmatter description with Use when, Use for, or Use to.',
+ );
+ });
+
+ test('errors when description is multiline or over 300 chars', () => {
+ const skillPath = createSkill(
+ 'description-errors',
+ `---
+name: description-errors
+description: |
+ ${'Validate metadata. Use when checking descriptions.'.padEnd(301, 'x')}
+---
+
+# Description Errors
+
+Validate description metadata before handoff.
+
+## Instructions
+
+1. Validate descriptions.
+
+## References
+`,
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Rewrite frontmatter description as a single YAML line.',
+ );
+ expect(result.report.errors).toContain(
+ 'Shorten description to 300 characters or fewer. Current length: 301.',
+ );
+ });
+
+ test('validates title, purpose, required sections, heading order, and final references', () => {
+ const skillPath = createSkill(
+ 'bad-body',
+ `---
+name: bad-body
+description: Validate skill body structure. Use when checking headings and purpose.
+---
+
+Intro before title.
+
+## References
+
+## Rules
+
+## Extra
+`,
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Make the first non-empty body line an H1 title, for example: # Skill Name.',
+ );
+ expect(result.report.errors).toContain(
+ 'Add one non-empty, non-heading purpose line immediately after the H1 title and before the first H2.',
+ );
+ expect(result.report.errors).toContain(
+ 'Add required section ## Instructions.',
+ );
+ expect(result.report.errors).toContain(
+ 'Remove unsupported H2 section ## Extra. Allowed H2 sections are ## Prerequisites, ## Instructions, ## Rules, ## Completion Gate, ## Next Steps, ## References.',
+ );
+ expect(result.report.errors).toContain(
+ 'Move ## Rules before ## References to match the canonical section order.',
+ );
+ expect(result.report.errors).toContain(
+ 'Move ## References to the final H2 section.',
+ );
+ });
+
+ test('errors when included canonical sections do not start with required intro lines', () => {
+ const skillPath = createSkill(
+ 'bad-intros',
+ validSkillMd({
+ name: 'bad-intros',
+ sections: `## Prerequisites
+
+## Instructions
+
+Start with another instruction explanation.
+
+1. Validate intros.
+
+## Rules
+
+Start with another rules explanation.
+
+- MUST validate intros.
+
+## Completion Gate
+
+Start with another completion explanation.
+
+- [ ] Intros were validated.
+
+## Next Steps
+
+Start with another next step explanation.
+
+- Continue after validation.
+
+## References
+
+Start with another reference explanation.
+`,
+ }),
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Start ## Prerequisites with: ALL prerequisites MUST be true before following this skill.',
+ );
+ expect(result.report.errors).toContain(
+ 'Start ## Instructions with: Follow these steps IN ORDER. Do NOT skip steps.',
+ );
+ expect(result.report.errors).toContain(
+ 'Start ## Rules with: These rules are MANDATORY.',
+ );
+ expect(result.report.errors).toContain(
+ 'Start ## Completion Gate with: Do NOT leave this skill until ALL items are complete.',
+ );
+ expect(result.report.errors).toContain(
+ 'Start ## Next Steps with: Once the completion gate is fully checked:',
+ );
+ expect(result.report.errors).toContain(
+ 'Start ## References with: Use these references when you need detail.',
+ );
+ });
+
+ test('allows extra text after required intro lines and checks only present sections', () => {
+ const skillPath = createSkill(
+ 'extra-intro-text',
+ validSkillMd({
+ name: 'extra-intro-text',
+ sections: `## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps. Extra same-line guidance is allowed.
+
+1. Validate intros.
+
+## References
+
+Use these references when you need detail. Extra same-line guidance is allowed.
+`,
+ }),
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(0);
+ expect(result.report.valid).toBe(true);
+ expect(result.report.errors).toEqual([]);
+ });
+
+ test('warns over 50 body lines and exits 0 when only warnings exist', () => {
+ const bodyLines = Array.from(
+ { length: 44 },
+ (_, index) => `Extra body line ${index + 1}`,
+ ).join('\n');
+ const skillPath = createSkill(
+ 'warning-skill',
+ validSkillMd({
+ name: 'warning-skill',
+ sections: `## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Validate warnings.
+
+${bodyLines}
+
+## References
+
+Use these references when you need detail.
+`,
+ }),
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(0);
+ expect(result.report.valid).toBe(true);
+ expect(result.report.warnings).toContain(
+ 'Move detail out of SKILL.md; body has 51 non-empty lines and should stay at or below 50.',
+ );
+ });
+
+ test('errors over 80 body lines', () => {
+ const bodyLines = Array.from(
+ { length: 74 },
+ (_, index) => `Extra body line ${index + 1}`,
+ ).join('\n');
+ const skillPath = createSkill(
+ 'long-skill',
+ validSkillMd({
+ name: 'long-skill',
+ sections: `## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Validate length.
+
+${bodyLines}
+
+## References
+
+Use these references when you need detail.
+`,
+ }),
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Move detail out of SKILL.md; body has 81 non-empty lines and must stay at or below 80.',
+ );
+ });
+
+ test('validates artifact placement and final references bullets', () => {
+ const skillPath = createSkill(
+ 'artifact-checks',
+ validSkillMd({
+ name: 'artifact-checks',
+ sections: `## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Use [ignored outside references](assets/linked-outside.md).
+
+## References
+
+Use these references when you need detail.
+
+- [assets/template.md](assets/wrong.md) - Template file.
+- [references/missing.md](references/missing.md) - Missing file.
+- [scripts/helper.js](scripts/helper.js) -
+`,
+ }),
+ {
+ 'assets/linked-outside.md': 'outside link only',
+ 'assets/template.md': 'template',
+ 'references/nested/example.md': 'nested',
+ 'scripts/helper.js': 'helper',
+ },
+ );
+
+ const result = runValidator([skillPath]);
+
+ expect(result.status).toBe(1);
+ expect(result.report.errors).toContain(
+ 'Move nested artifact references/nested/example.md directly under references/; nested artifact files are not allowed.',
+ );
+ expect(result.report.errors).toContain(
+ 'Reference artifact assets/template.md with matching text and href: - [assets/template.md](assets/template.md) - short description.',
+ );
+ expect(result.report.errors).toContain(
+ 'Create linked artifact references/missing.md or remove its References bullet.',
+ );
+ expect(result.report.errors).toContain(
+ 'Add a short description after " - " for artifact reference scripts/helper.js.',
+ );
+ expect(result.report.errors).toContain(
+ 'Link artifact assets/linked-outside.md from the final ## References section.',
+ );
+ });
+});