semantu-agents 1.2.0 → 1.2.2

package/README.md

@@ -1,53 +1,110 @@
 # semantu-agents
 
-Reusable Claude Code skills and hooks for Semantu projects.
+Reusable Claude Code and agent skills for Semantu projects.
 
-Public skills are shipped with the npm package and work everywhere. Private skills require git access to the agents repo.
-
-## Project setup
+## Recommended: Global Install
 
 ```bash
-npx semantu-agents
+npx semantu-agents global
 ```
 
-Syncs public skills from npm, tries to clone the agents repo for private skills (skips gracefully without access), patches `package.json` and `.gitignore`, and syncs all skills to `.claude/skills/` and `.agents/skills/`.
+Syncs the npm-packaged public skills to:
+
+- `~/.claude/skills`
+- `~/.agents/skills`
+
+This is the default recommended setup. It keeps application repos clean and makes the shared skills available across projects. Project repos can still define app-specific skills separately.
+
+## Updating Global Skills
+
+For normal users, rerun:
+
+```bash
+npx semantu-agents global
+```
 
-Add to `package.json` so it runs on setup:
+For contributors with an editable checkout at `~/.agents-src`, run this from anywhere:
 
-```json
-{
-  "scripts": {
-    "setup": "npx semantu-agents"
-  }
-}
+```bash
+npx semantu-agents update
 ```
 
-## Global setup
+This updates `~/.agents-src/main`, syncs it to `~/.claude/skills` and `~/.agents/skills`, then restores your previous branch when possible. If `~/.agents-src` has uncommitted changes, commit or stash them first.
+
+## Contributing Skill Changes
+
+Install an editable source checkout:
 
 ```bash
-npx semantu-agents --global
+npx semantu-agents dev
 ```
 
-Syncs skills to `~/.claude/skills/` and `~/.agents/skills/`. This makes skills available to Claude Code and Codex across all projects without per-repo setup.
+This clones or pulls `github.com:Semantu/agents` into `~/.agents-src`, installs a post-merge hook, and syncs that checkout globally.
 
-## Editing skills
+Dev mode requires repo access. If cloning fails, ask for access to the Semantu agents repo.
 
-Edit directly in `packages/semantu-agents/skills/`, then commit and push:
+Make changes in the source checkout only:
 
 ```bash
-cd packages/semantu-agents
+cd ~/.agents-src
 git checkout -b my-change
-# edit skills...
-git add -A && git commit -m "improve workflow skill"
+# edit skills/public/... or skills/private/...
+npm run sync
+git add .
+git commit -m "improve workflow skill"
 git push -u origin my-change
+gh pr create
+```
+
+Do not edit these generated folders directly:
+
+- `~/.claude/skills`
+- `~/.agents/skills`
+
+They are overwritten by `semantu-agents global`, `semantu-agents sync`, and `semantu-agents update`.
+
+The dev post-merge hook runs `node cli.mjs sync` after pulls, so merged changes are synced globally automatically.
+
+## Project Setup
+
+Project-local setup is still available for repos that intentionally want checked-out helper files:
+
+```bash
+npx semantu-agents
 ```
 
-To re-sync after editing:
+Most projects should prefer the global install instead.
+
+## Docs index
+
+Print a markdown or JSON index of docs that use YAML frontmatter.
 
 ```bash
-npm run sync:agents
+npx semantu-agents docs
+npx semantu-agents docs ideas
+npx semantu-agents docs architecture
+npx semantu-agents docs --all
+npx semantu-agents docs --format markdown
+npx semantu-agents docs --all --format json
 ```
 
+Supported scopes:
+
+- `root` (default) -> `docs/*.md`
+- `architecture` -> `docs/architecture/*.md`
+- `ideas` -> `docs/ideas/*.md`
+- `plans` -> `docs/plans/*.md`
+- `reports` -> `docs/reports/*.md`
+
+Notes:
+
+- default output is text
+- supported formats: `text`, `markdown`, `json`
+- JSON uses short keys: `f` = file, `s` = summary, `d` = folder
+- `--all` adds a folder column in markdown, or `d` in JSON
+- `--fix` adds an empty `summary` field when frontmatter is missing it
+- missing summaries stay blank; the command does not warn
+
 ## Skill layout
 
 ```

package/cli.mjs

@@ -1,29 +1,33 @@
 #!/usr/bin/env node
 
-/**
- * semantu-agents — CLI that syncs public skills from npm and private skills from git.
- *
- * Usage:
- *   npx semantu-agents           — sync public skills + try git clone for private skills
- *   npx semantu-agents --global  — sync to ~/.claude/ and ~/.agents/ for all projects
- *
- * Public skills are always available (shipped with the npm package).
- * Private skills require git access to github.com:Semantu/agents.
- */
-
-import {cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
+import {execSync} from 'node:child_process';
+import {cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync} from 'node:fs';
 import {homedir} from 'node:os';
 import path from 'node:path';
-import {execSync} from 'node:child_process';
 import {fileURLToPath} from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const command = args[0];
+
+const projectRoot = process.cwd();
 const skillsRepo = 'git@github.com:Semantu/agents.git';
+const DOC_FOLDERS = {
+  root: 'docs',
+  architecture: path.join('docs', 'architecture'),
+  ideas: path.join('docs', 'ideas'),
+  plans: path.join('docs', 'plans'),
+  reports: path.join('docs', 'reports'),
+};
 
 function run(cmd, opts) {
   return execSync(cmd, {stdio: 'inherit', ...opts});
 }
 
+function output(cmd, opts) {
+  return execSync(cmd, {encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts}).trim();
+}
+
 function cloneOrPull(dir) {
   if (existsSync(path.join(dir, '.git'))) {
     console.log('Updating agents repo...');
@@ -34,11 +38,23 @@ function cloneOrPull(dir) {
   }
 }
 
-/**
- * Sync skills from a source directory into target directories.
- * Copies each skill folder individually so public and private merge into
- * the same flat target directory.
- */
+function cloneIfMissing(dir) {
+  if (existsSync(path.join(dir, '.git'))) {
+    console.log('Using existing editable agents repo at ~/.agents-src');
+  } else {
+    console.log('Cloning agents repo...');
+    run(`git clone ${skillsRepo} ${dir}`);
+  }
+}
+
+function globalTargets() {
+  const home = homedir();
+  return [
+    path.join(home, '.claude', 'skills'),
+    path.join(home, '.agents', 'skills'),
+  ];
+}
+
 function syncSkillsInto(skillsSource, targets) {
   if (!existsSync(skillsSource)) return;
 
@@ -48,33 +64,81 @@ function syncSkillsInto(skillsSource, targets) {
   }
 }
 
-function setupGlobal() {
-  const home = homedir();
-  const targets = [
-    path.join(home, '.claude', 'skills'),
-    path.join(home, '.agents', 'skills'),
-  ];
+function syncFromSource(sourceDir, label = 'source checkout', options = {}) {
+  const includePrivate = options.includePrivate ?? true;
+  const targets = globalTargets();
+  const publicSkills = path.join(sourceDir, 'skills', 'public');
+  const privateSkills = path.join(sourceDir, 'skills', 'private');
 
-  // 1. Always sync public skills from the npm package
-  const publicSkills = path.join(__dirname, 'skills', 'public');
   for (const dest of targets) {
     rmSync(dest, {recursive: true, force: true});
   }
-  syncSkillsInto(publicSkills, targets);
-  console.log('Synced public skills from npm package');
 
-  // 2. Try to clone/pull for private skills
-  const srcDir = path.join(home, '.agents-src');
-  try {
-    cloneOrPull(srcDir);
-    const privateSkills = path.join(srcDir, 'skills', 'private');
+  syncSkillsInto(publicSkills, targets);
+  if (includePrivate) {
     syncSkillsInto(privateSkills, targets);
-    console.log('Synced private skills from git repo');
-  } catch {
-    console.log('Skipped private skills — no git access to agents repo.');
   }
 
-  console.log('\nDone. Skills synced globally to ~/.claude/skills/ and ~/.agents/skills/');
+  console.log(`Synced skills from ${label} -> ~/.claude/skills/ and ~/.agents/skills/`);
+}
+
+function setupGlobal() {
+  syncFromSource(__dirname, 'npm package', {includePrivate: false});
+  console.log('\nDone. Public skills synced globally. Run `npx semantu-agents dev` to install an editable source checkout.');
+}
+
+function installPostMergeHook(repoDir) {
+  const hooksDir = path.join(repoDir, '.git', 'hooks');
+  const hookPath = path.join(hooksDir, 'post-merge');
+  const hook = `#!/bin/sh
+cd "$(git rev-parse --show-toplevel)" && node cli.mjs sync
+`;
+
+  mkdirSync(hooksDir, {recursive: true});
+  writeFileSync(hookPath, hook, {mode: 0o755});
+  console.log('Installed post-merge hook to sync global skills after pulls');
+}
+
+function setupDev() {
+  const srcDir = path.join(homedir(), '.agents-src');
+
+  cloneIfMissing(srcDir);
+  installPostMergeHook(srcDir);
+  syncFromSource(srcDir, '~/.agents-src');
+
+  console.log('\nDone. Edit skills in ~/.agents-src, run `node cli.mjs sync`, then commit and open a PR.');
+}
+
+function syncGlobalFromCurrentCheckout() {
+  syncFromSource(__dirname, 'current checkout');
+}
+
+function updateDevCheckout() {
+  const srcDir = path.join(homedir(), '.agents-src');
+
+  if (!existsSync(path.join(srcDir, '.git'))) {
+    console.log('No editable checkout found at ~/.agents-src.');
+    console.log('Run `npx semantu-agents dev` if you have access to github.com:Semantu/agents.');
+    process.exit(1);
+  }
+
+  const currentBranch = output('git branch --show-current', {cwd: srcDir});
+  const dirty = output('git status --porcelain', {cwd: srcDir});
+
+  if (dirty) {
+    console.log('Cannot update ~/.agents-src because it has uncommitted changes.');
+    console.log('Commit, stash, or discard them, then rerun `npx semantu-agents update`.');
+    process.exit(1);
+  }
+
+  run('git fetch origin main', {cwd: srcDir});
+  run('git switch main', {cwd: srcDir});
+  run('git pull --ff-only origin main', {cwd: srcDir});
+  syncFromSource(srcDir, '~/.agents-src');
+
+  if (currentBranch && currentBranch !== 'main') {
+    run(`git switch ${currentBranch}`, {cwd: srcDir});
+  }
 }
 
 function setupProject() {
@@ -105,7 +169,6 @@ function setupProject() {
     console.log('Skipped private skills — no git access to agents repo.');
   }
 
-  // 3. Patch package.json scripts
   const pkgPath = path.join(projectRoot, 'package.json');
   if (existsSync(pkgPath)) {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
@@ -128,7 +191,6 @@ function setupProject() {
     }
   }
 
-  // 4. Patch .gitignore
   const ignorePath = path.join(projectRoot, '.gitignore');
   const ignoreEntries = ['packages/', '.claude/', '.agents/'];
   let ignoreContent = existsSync(ignorePath) ? readFileSync(ignorePath, 'utf8') : '';
@@ -146,7 +208,6 @@ function setupProject() {
     console.log('Updated .gitignore');
   }
 
-  // 5. Ensure docs directories exist
   for (const dir of ['docs/ideas', 'docs/plans', 'docs/reports']) {
     const fullPath = path.join(projectRoot, dir);
     if (!existsSync(fullPath)) {
@@ -156,12 +217,193 @@ function setupProject() {
   }
 }
 
-// --- Main ---
+function parseDocsArgs(inputArgs) {
+  const options = {
+    format: 'text',
+    fix: false,
+    all: false,
+    scope: 'root',
+    dir: projectRoot,
+  };
+
+  for (let i = 0; i < inputArgs.length; i += 1) {
+    const arg = inputArgs[i];
+
+    if (arg === '--all') {
+      options.all = true;
+      continue;
+    }
+    if (arg === '--fix') {
+      options.fix = true;
+      continue;
+    }
+    if (arg === '--format') {
+      options.format = inputArgs[i + 1] || 'markdown';
+      i += 1;
+      continue;
+    }
+    if (arg === '--dir') {
+      options.dir = path.resolve(projectRoot, inputArgs[i + 1] || '.');
+      i += 1;
+      continue;
+    }
+    if (arg === 'json' || arg === 'markdown' || arg === 'text') {
+      options.format = arg;
+      continue;
+    }
+    if (arg === 'all') {
+      options.all = true;
+      continue;
+    }
+    if (Object.hasOwn(DOC_FOLDERS, arg)) {
+      options.scope = arg;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function listMarkdownFiles(dirPath) {
+  if (!existsSync(dirPath)) {
+    return [];
+  }
+
+  return readdirSync(dirPath)
+    .filter(name => name.endsWith('.md'))
+    .filter(name => statSync(path.join(dirPath, name)).isFile())
+    .sort()
+    .map(name => path.join(dirPath, name));
+}
+
+async function ensureSummary(filePath) {
+  const {default: matter} = await import('gray-matter');
+  const source = readFileSync(filePath, 'utf8');
+  const parsed = matter(source);
+
+  if (typeof parsed.data.summary === 'string') {
+    return;
+  }
+
+  writeFileSync(
+    filePath,
+    matter.stringify(parsed.content, {
+      summary: '',
+      ...parsed.data,
+    }),
+  );
+}
+
+function escapeCell(value) {
+  return String(value || '')
+    .replace(/\n+/g, ' ')
+    .replace(/\|/g, '\\|')
+    .trim();
+}
+
+async function loadEntries(scope, options) {
+  const {default: matter} = await import('gray-matter');
+  const folderPath = path.join(options.dir, DOC_FOLDERS[scope]);
+  const files = listMarkdownFiles(folderPath);
+
+  if (options.fix) {
+    for (const file of files) {
+      await ensureSummary(file);
+    }
+  }
+
+  return files.map(filePath => {
+    const parsed = matter(readFileSync(filePath, 'utf8'));
+    return {
+      folder: scope,
+      file: path.basename(filePath),
+      summary: typeof parsed.data.summary === 'string' ? parsed.data.summary : '',
+    };
+  });
+}
+
+function renderMarkdown(entries, includeFolder) {
+  const header = includeFolder
+    ? ['| folder | file | summary |', '|--------|------|---------|']
+    : ['| file | summary |', '|------|---------|'];
+
+  const rows = entries.map(entry =>
+    includeFolder
+      ? `| ${escapeCell(entry.folder)} | ${escapeCell(entry.file)} | ${escapeCell(entry.summary)} |`
+      : `| ${escapeCell(entry.file)} | ${escapeCell(entry.summary)} |`,
+  );
+
+  return [...header, ...rows].join('\n');
+}
+
+function renderText(entries, includeFolder) {
+  if (includeFolder) {
+    const lines = [];
+    let currentFolder = null;
+
+    for (const entry of entries) {
+      if (entry.folder !== currentFolder) {
+        if (lines.length > 0) {
+          lines.push('');
+        }
+        currentFolder = entry.folder;
+        lines.push(entry.folder);
+      }
+
+      lines.push(`  ${entry.file}`);
+      if (entry.summary) {
+        lines.push(`    ${entry.summary}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  return entries
+    .flatMap(entry =>
+      entry.summary ? [entry.file, `  ${entry.summary}`] : [entry.file],
+    )
+    .join('\n');
+}
+
+function renderJson(entries, includeFolder) {
+  const rows = entries.map(entry =>
+    includeFolder
+      ? {d: entry.folder, f: entry.file, s: entry.summary}
+      : {f: entry.file, s: entry.summary},
+  );
+
+  return JSON.stringify(rows, null, 2);
+}
+
+async function docs(inputArgs) {
+  const options = parseDocsArgs(inputArgs);
+  const scopes = options.all ? Object.keys(DOC_FOLDERS) : [options.scope];
+  const entries = (await Promise.all(scopes.map(scope => loadEntries(scope, options)))).flat();
+  const includeFolder = options.all;
+
+  const output =
+    options.format === 'json'
+      ? renderJson(entries, includeFolder)
+      : options.format === 'markdown'
+        ? renderMarkdown(entries, includeFolder)
+        : renderText(entries, includeFolder);
+
+  process.stdout.write(`${output}\n`);
+}
 
 const isGlobal = process.argv.includes('--global') || process.argv.includes('-g');
 
-if (isGlobal) {
+if (command === 'docs') {
+  await docs(args.slice(1));
+} else if (command === 'global' || isGlobal) {
   setupGlobal();
+} else if (command === 'dev') {
+  setupDev();
+} else if (command === 'sync') {
+  syncGlobalFromCurrentCheckout();
+} else if (command === 'update') {
+  updateDevCheckout();
 } else {
   setupProject();
 }

package/package.json

@@ -1,17 +1,15 @@
 {
   "name": "semantu-agents",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Reusable Claude Code skills and hooks for Semantu projects",
   "type": "module",
-  "bin": {
-    "semantu-agents": "cli.mjs"
-  },
+  "bin": "cli.mjs",
   "files": [
     "cli.mjs",
     "skills/public"
   ],
   "scripts": {
-    "sync": "node sync.mjs"
+    "sync": "node cli.mjs sync"
   },
   "publishConfig": {
     "access": "public"
@@ -19,5 +17,8 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
   }
 }

package/skills/public/explore/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: explore
+description: Deeply evaluate a topic with context, 3 viable approaches, tradeoffs, and a recommendation without forcing a full ideation-mode cycle.
+---
+
+# Instructions
+
+## Objective
+
+Provide a reusable deep-dive format for `explore <topic>` in any mode, including decomposition of broad topics into concrete decisions.
+
+## Entry gate
+
+Run this skill when the user explicitly says `explore <topic>` (or clearly asks to explore a topic in this format).
+
+## Steps
+
+1. Confirm scope only if the topic is ambiguous; otherwise proceed directly.
+2. Decompose the topic into decision candidates and unknowns.
+3. For each decision, classify as `must decide now` or `can defer`.
+4. For each `must decide now` decision, give concise context and assumptions, then provide exactly 3 viable approaches (A-C).
+5. For each approach, list pros, cons, and risks.
+6. Recommend one approach (A/B/C) with a one-line rationale.
+7. If there are multiple decisions, present them in batches of 3 by default (use fewer only when fewer remain or when the user asks for a different batch size). Start with `Decision x-y of N`, and end with `Recap: 1A 2C 3B`; ask for agreement or edits.
+8. Iterate until consent; no feedback on a decision counts as acceptance after an explicit agreement prompt.
+9. Recurse only for nested decisions classified as `must decide now`; defer the rest. Default max depth is 2 unless the user asks for deeper drilldown.
+10. After consent, ask whether to continue the current mode or switch modes.
+
+## Guardrails
+
+- Do not force a mode switch by default; this skill can run inside any active mode.
+- Do not create ideation/plan artifacts unless the active mode requires them or the user asks.
+- Keep outputs structured and concise; avoid repeating unchanged context.
+- Do not recurse indefinitely; respect the depth cap and defer non-blocking items.

package/skills/public/ideation/SKILL.md

@@ -7,99 +7,35 @@ description: Explore and compare candidate implementation routes before committi
 
 ## Objective
 
-Interactively explore implementation routes and architecture choices with the user through conversation, recording progress in an ideation document.
+Surface unknowns, assumptions, and architecture choices before committing to a plan.
 
 ## Entry gate
 
-Run this mode only after the user explicitly confirms ideation mode for the current task.
+Run this mode when the user explicitly chooses ideation, or when workflow routes brainstorming into ideation.
 
 ## Steps
 
-### 1. Understand context
-
-Spawn one or more subagents to explore the codebase concurrently. Give each subagent a focused research question — e.g. "find all files related to authentication and summarize the current flow", "read the test suite for module X and report what it covers". Do not read large files or trace dependencies directly in the main agent; let subagents do the heavy lifting and report back.
-
-Synthesize subagent findings into the Context section of the ideation doc. Summarise the problem space and goals back to the user in chat to confirm shared understanding.
-
-### 2. Create the ideation document
-
-Create/update `docs/ideas/<nnn>-<topic>.md` as a progress tracker (NOT the primary output — chat is).
-
-- For new docs, `<nnn>` MUST be the next available 3-digit prefix in `docs/ideas`.
-- Use this structure:
-
-```markdown
-# <Topic> — Ideation
-
-## Context
-<problem statement, relevant code references>
-
-## Goals
-<what we're trying to achieve>
-
-## Open Questions
-- [ ] Question 1
-- [ ] Question 2
-
-## Decisions
-| # | Decision | Chosen | Rationale |
-|---|----------|--------|-----------|
-
-## Notes
-<scratchpad for explored approaches, discarded ideas>
-```
-
-### 3. Identify everything that needs deciding
-
-Before proposing solutions, discover and list all decision points:
-- Open questions about scope and requirements
-- Architecture decisions needed
-- Technical unknowns requiring investigation
-- Constraints and dependencies
-
-Present this list to the user and ask if anything is missing.
-
-### 4. Walk through decisions one at a time
-
-For each decision point, present in chat:
-- **Full context** — relevant code snippets, existing patterns, constraints
-- **2–3 approaches** with concrete code examples where helpful
-- **Pros/cons** for each approach
-- **Recommended path** with reasoning
-
-**Progress indicator:** Always tell the user where they are — e.g. "Decision 2 of 5" or "Gap 3 of 4" — so they know how many remain before the next mode.
-
-When assessing the viability of a specific approach requires reading code or checking feasibility, spawn a research subagent for that investigation and incorporate its findings into the discussion. Do not spawn subagents for the creative work of generating approaches — that stays with the main agent.
-
-Wait for the user's input before moving to the next decision. Do not batch multiple decisions into one message.
-
-### 5. Record as you go
-
-After each decision is made:
-- Check off the resolved question in Open Questions
-- Add a row to the Decisions table
-- Update Notes with any useful context that came up
-
-### 6. Check for completeness
-
-After working through the list, review what remains:
-- Are all open questions resolved?
-- Are there new questions that surfaced during discussion?
-- Does the user want to explore anything further?
-
-Keep iterating until everything is decided.
+1. Read relevant code, tests, and docs first.
+2. Create/update `docs/ideas/<nnn>-<topic>.md`.
+   - For new ideation docs, `<nnn>` MUST be the next available 3-digit prefix in `docs/ideas`.
+   - Every new ideation doc MUST start with YAML frontmatter containing at least a summary key.
+3. Discover impacted repo/package test surfaces:
+   - Locate changed package roots (root repo and/or `packages/<name>` roots as applicable).
+   - For each impacted package, identify quick test commands (target total runtime 1-2 minutes), full/slow test commands, and where each was found (`package.json` scripts first, README fallback).
+   - Record unknowns/gaps when no reliable quick regression command exists.
+4. Build a decision map: list major decisions, unknowns, and research gaps.
+5. Classify each item as `must decide now` (blocks planning) or `can defer`.
+6. Use the `explore` skill for each `must decide now` decision/topic.
+7. Record accepted choices, deferred unknowns, and discovered test surfaces in the ideation doc.
+8. Continue until blocking decisions reach consent; then ask whether to switch to `plan` mode.
 
 ## Guardrails
 
-- **Chat is the primary medium.** The ideation doc tracks progress — it is not the deliverable.
 - Do not write implementation code in this mode.
-- Do not batch multiple unrelated decisions into a single message.
-- Do not suggest plan mode until all open questions are resolved and the user confirms nothing is left.
+- Do not convert ideation into a plan unless the user explicitly requests it.
 
 ## Exit criteria
 
-- All open questions in the ideation doc are checked off.
-- All architecture decisions have a chosen approach recorded.
-- User has explicitly confirmed next step. Offer:
-  - **Plan mode** (default) — continue manually through the workflow.
-  - **Automatic mode** — switch to automatic mode and run plan → tasks → implementation → review autonomously.
+- Blocking decisions and deferred unknowns are documented.
+- User feedback has narrowed choices.
+- User has explicitly confirmed whether to switch to plan mode or stay in ideation mode.

package/skills/public/implementation/SKILL.md

@@ -14,12 +14,14 @@ Run only after explicit user confirmation to enter implementation mode, with an
 1. Confirm the approved plan exists on disk at `docs/plans/<nnn>-<topic>.md`. Tool-native plan mode alone is not sufficient.
 2. If this plan stems from an ideation doc, remove the originating ideation doc in `docs/ideas` when implementation begins.
 3. Implement one planned phase at a time.
-4. Run the phase validation criteria and record results.
+4. Run the phase validation criteria and record results, including the quick regression gate for impacted packages (target total runtime 1-2 minutes).
 5. After a phase is completed, update `docs/plans/<nnn>-<topic>.md` to reflect completed work and mark phase status. This update is mandatory before moving to the next phase.
 6. Create one commit per phase, including code changes and the phase-completion plan update in the same commit.
 7. Continue to next phase without pausing only if there are no deviations and no major problems.
 8. If any deviation/blocker/major risk appears, pause and report.
 
+Full/slow test suites may be deferred until review by default. Run deferred suites earlier only if the user requests it.
+
 ## Parallel execution
 
 When the plan marks phases as parallelizable, use the Task tool (or any available sub-agent spawning tool) to run them concurrently:
@@ -47,6 +49,7 @@ When the plan marks phases as parallelizable, use the Task tool (or any availabl
 - If the originating ideation doc is ambiguous, pause and ask the user which ideation file to remove.
 - Do not skip plan updates between completed phases.
 - Do not switch to review/wrapup implicitly; ask the user to explicitly confirm the next mode.
+- Do not mark a phase complete if its quick regression gate fails.
 
 ## Exit criteria
 

package/skills/public/plan/SKILL.md

@@ -13,6 +13,7 @@ Run only when the user explicitly confirms plan mode (for example: converting id
 
 1. Create/update `docs/plans/<nnn>-<topic>.md`. This on-disk plan file is mandatory.
    - When creating a new plan doc (including ideation -> plan conversion), `<nnn>` MUST be the next available 3-digit prefix in `docs/plans`.
+   - Every new plan doc MUST start with YAML frontmatter containing at least a summary key.
 2. Focus on chosen route(s), not all explored options.
 3. **Carry forward all decided features and details from the ideation doc.** Every feature, API surface, design detail, and example that was explored and not explicitly rejected must appear in the plan. No idea can be silently dropped. If unsure whether something was tentatively discussed or firmly decided, ask the user for clarification rather than omitting it.
 4. Include:
@@ -22,8 +23,14 @@ Run only when the user explicitly confirms plan mode (for example: converting id
    - Potential pitfalls
    - Remaining unclear areas/decisions
    - **Inter-component contracts**: When the architecture has separable parts (layers, modules, packages), make the contracts between them explicit — type definitions, function signatures, shared data structures. These contracts enable parallel implementation in tasks mode.
+   - **Test strategy**:
+     - impacted repo/package list
+     - quick regression gate commands (target total runtime 1-2 minutes) to run after each phase
+     - full/slow test commands deferred to review
+     - command source notes (`package.json` scripts and/or README)
+     - explicit skip/defer rationale for slow suites
 5. Mention tradeoffs only to explain why chosen paths were selected.
-5. Continuously refine the plan with user feedback until it is explicitly approved for implementation.
+6. Continuously refine the plan with user feedback until it is explicitly approved for implementation.
 
 ## Guardrails
 

package/skills/public/review/SKILL.md

@@ -16,6 +16,7 @@ Run only when the user explicitly confirms review mode.
 3. Identify what is still missing to make this work more complete.
 4. Identify gaps or risks in the current implementation.
 5. Identify likely future work required for fuller completeness.
+6. Re-run deferred full/slow test suites for all impacted repos/packages from the plan's test strategy, and report pass/fail with any skipped checks and reasons.
 
 ## Parallel review via subagents
 
@@ -102,12 +103,14 @@ The ideation within this section follows the same rules as the ideation skill:
 - Only convert review findings into iteration content after the user confirms which gaps to address.
 - For newly uncovered work, always go through ideation first — never skip straight to tasks or implementation.
 - If the user's response involves clarifying approach or scope, treat this as still in the clarification loop — ask follow-ups for any remaining ambiguity.
+- Do not claim review completion without test evidence for impacted packages (or explicit user-approved skips).
 
 ## Exit criteria
 
 - Gaps are triaged with explicit user decisions (now vs defer).
 - If iterating: ideation for all selected gaps is recorded in the plan doc, and user has confirmed next step.
 - If deferring: ideation docs were created for deferred gaps.
+- Deferred full/slow test suites for impacted packages were executed and reported, or explicitly skipped with user approval.
 - User has explicitly confirmed whether to:
   - **Iterate** — proceed to plan the ideated gaps (manually via plan mode, or via automatic mode for plan → tasks → implementation → review)
   - **Wrapup** — no more work needed, move to wrapup mode

package/skills/public/tasks/SKILL.md

@@ -15,8 +15,12 @@ Run only when the user explicitly confirms tasks mode.
 2. Define implementation phases.
 3. Define concrete tasks under each phase.
 4. Add explicit validation criteria per phase (for example: unit tests, integration tests, build/typecheck commands, targeted runtime checks).
-5. Write detailed test specifications for every phase (see **Test specification** below).
-6. Ensure phases are commit-friendly (one commit per phase).
+5. For every phase, define:
+   - phase-specific tests to add/update when behavior/API changes,
+   - a quick regression gate using discovered package test commands (target total runtime 1-2 minutes),
+   - full/slow suites deferred to review.
+6. Write detailed test specifications for every phase (see **Test specification** below).
+7. Ensure phases are commit-friendly (one commit per phase).
 
 ## Parallel execution
 
@@ -33,6 +37,10 @@ Phases should be designed for maximum parallelism — different agents may imple
 
 Every phase must include a **Validation** section that describes the checks an implementing agent must perform and pass before considering the phase complete. Validation is not limited to coded tests — it includes any check that truly proves the work is correct.
 
+Validation must separate:
+- **Quick phase gate**: checks that should finish in 1-2 minutes total and must pass after each phase.
+- **Full review gate**: slow suites deferred to review unless the user requests earlier execution.
+
 **Types of validation checks** (use whichever are appropriate for the phase):
 - **Unit/integration tests**: Coded test files with named test cases and concrete assertions.
 - **Compilation/type-check**: e.g. `npm run compile` passes with no errors.

package/skills/public/workflow/SKILL.md

@@ -9,6 +9,12 @@ description: Enforce the explicit mode cadence (ideation -> plan -> tasks -> imp
 
 - Default for any task that touches code or modifies planning/docs.
 
+## Shortcut triggers
+
+- If the user says `explore <topic>`, run the `explore` skill immediately, even when already inside another mode.
+- `explore` is a deep-dive formatting shortcut, not a mode switch by itself.
+- After finishing an `explore` pass, ask whether to continue the current mode or switch modes.
+
 ## Mode selection at task start
 
 - If the user has already explicitly chosen a mode (or explicitly called a mode skill), enter that mode directly.
@@ -51,6 +57,16 @@ These transition gates apply to standard modes. `automatic` mode is an explicit
 - `review`: emit findings in chat first; after user decisions, update plan with now-work tasks and/or create ideation docs for deferred future work
 - `wrapup`: convert plan into a final report doc in `docs/reports`, then remove the plan doc after report approval
 
+## Frontmatter requirements for docs
+
+- Any new doc created under `docs/ideas`, `docs/plans`, `docs/reports`, or `docs/architecture` MUST start with YAML frontmatter.
+- Minimum required frontmatter for new docs:
+  ```yaml
+  ---
+  summary: One or two lines describing the document.
+  ---
+  ```
+
 ## Global constraints
 
 - Tool-native plan modes do NOT replace the on-disk plan file requirement.

package/skills/public/wrapup/SKILL.md

@@ -24,6 +24,13 @@ Also treat any user request to prepare/open/update a PR, or draft PR title/body/
 5. Update `docs/plans/<nnn>-<topic>.md` by appending a `## REVIEW` section at the end with wrapup outcomes and PR-readiness status.
 6. Convert `docs/plans/<nnn>-<topic>.md` into a report doc in `docs/reports/<nnn>-<topic>.md`.
    - For this conversion, the report `<nnn>` MUST be the next available 3-digit prefix in `docs/reports` (do not reuse the plan prefix when it conflicts).
+   - The report MUST start with YAML frontmatter containing a summary key.
+     ```yaml
+     ---
+     summary: One or two lines describing the final implemented outcome.
+     ---
+     ```
+   - When converting from a plan, rewrite the `summary` so it reflects the completed result and report scope, not the earlier proposed plan.
    - Update any references to the report path after conversion.
 7. **Report quality** — see the dedicated section below. The report is a condensed but comprehensive record of everything that was done. It is NOT a brief summary.
 8. **Remove the plan doc** `docs/plans/<nnn>-<topic>.md` after the report is written. Do not wait until after the PR — the plan must be gone before the final commit.