nova-spec 1.0.0

package/AGENTS.md

@@ -0,0 +1,61 @@
+# nova-spec — framework AGENTS.md
+
+> This repo uses CLAUDE.md as a stub → AGENTS.md is the instructions file.
+
+This repo is the **nova-spec framework itself** — a Spec-Driven Development (SDD) system for Claude Code. It's designed to be installed into other projects.
+
+## What is nova-spec
+
+Framework that orchestrates ticket-to-PR workflow with 7 slash commands: `/nova-start` → `/nova-spec` → `/nova-plan` → `/nova-build` → `/nova-review` → `/nova-wrap` → `/nova-status`.
+
+## Key commands
+
+- `/nova-start <TICKET>` — classify ticket, create branch, load context
+- `/nova-spec` — close requirements, generate spec (uses `close-requirement` skill)
+- `/nova-plan` — create plan + tasks
+- `/nova-build` — execute tasks one-by-one
+- `/nova-review` — final code review
+- `/nova-wrap` — commit, PR, update memory (uses `write-decision`, `update-service-context`)
+
+Quick-fixes skip `/nova-spec` and `/nova-plan`.
+
+## Branch config
+
+In `novaspec/config.yml`:
+- Pattern: `{type}/{ticket}-{slug}` (e.g., `feature/AGEX-123-new-feature`)
+- Types: bugfix, hotfix, feature, documentation, refactor, chore, architecture
+- Base branch: `main`
+
+## Memory structure
+
+```
+context/
+├── decisions/              # Why we did X (one file per decision)
+│   └── archived/           # Superseded (never auto-loaded by agents)
+├── gotchas/                # Non-obvious traps in the code
+├── services/               # Short map per service (≤80 lines, flat files)
+├── changes/
+│   ├── active/             # In-progress specs
+│   └── archive/            # Closed specs
+└── backlog/                # Pending proposals
+```
+
+Memory model: one fact = one file, filename = index, explicit supersede via `> Supersedes: <old>.md`. Wisdom about memory itself lives in `decisions/`, not in `AGENTS.md`.
+
+## Symlinks
+
+Claude Code discovers commands via `.claude/` symlinks pointing to `novaspec/`.
+
+## Working here
+
+This repo uses itself. When modifying nova-spec:
+1. Test changes in a worktree or sandbox project
+2. Verify symlinks work: `ls -la .claude/`
+3. Run through a full ticket cycle
+
+## Reference
+
+- Full docs: [README.md](./README.md)
+- Installation: [INSTALL.md](./INSTALL.md)
+- Commands: `novaspec/commands/*.md`
+- Skills: `novaspec/skills/*/SKILL.md`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adán González
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+<p align="center">
+  <img src="img/novaspec-logo.svg" alt="nova-spec" width="480">
+</p>
+
+<p align="center">
+  <strong>Spec-Driven Development on top of Claude Code.</strong><br>
+  From a ticket to a merged PR in explicit steps, with architectural memory that doesn't decay.
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <img alt="Status: experimental" src="https://img.shields.io/badge/status-experimental-orange.svg">
+  <img alt="Built for Claude Code" src="https://img.shields.io/badge/built%20for-Claude%20Code-purple.svg">
+</p>
+
+---
+
+## What it is
+
+`nova-spec` adds seven `/nova-*` commands to Claude Code that turn a ticket into a traceable change: classify, close requirements, plan, implement task by task, review, and wrap up with commit + PR + memory update. Memory (`context/decisions/`, `context/gotchas/`, `context/services/`) lives in atomic markdown files that humans edit and `grep` finds.
+
+It's not a template or a generator. It's a set of conventions + commands that Claude Code runs as slash commands inside your repo.
+
+## Who is this for
+
+- Developers using **Claude Code** (or OpenCode) on real projects, not toy demos.
+- Teams that want their AI agent to follow a **disciplined ticket → PR flow** instead of one-shotting code.
+- Anyone tired of **re-explaining the same architectural context** every new chat.
+
+If you only use Claude Code for one-off scripts, this is overkill. If you ship to production with it, read on.
+
+## Why it exists
+
+Without discipline, an agent writes code fast and loses the *why*. The next ticket forces you to re-explain the same context. `nova-spec` enforces human checkpoints, separates spec from executable tasks, and leaves a trail in `context/` so the next ticket starts informed.
+
+## Quickstart
+
+```bash
+# 1. Clone nova-spec on your machine (one time only)
+git clone https://github.com/adansuku/nova-spec.git ~/tools/nova-spec
+
+# 2. From the repo where you want to use it
+cd /path/to/your-project
+bash ~/tools/nova-spec/install.sh
+
+# 3. Open Claude Code and launch your first ticket
+claude
+/nova-start PROJ-123
+```
+
+Full details in [INSTALL.md](./INSTALL.md).
+
+## A taste of it
+
+What `/nova-start PROJ-42` actually does:
+
+```text
+> /nova-start PROJ-42
+
+Ticket: PROJ-42 — "Add rate limiting to /api/login"
+Classification: feature (2h-3d)
+Affected services: auth-api ✓
+
+Branch created: feature/PROJ-42-rate-limit-login (from main)
+
+Loaded context:
+  Services: auth-api ✓
+  Decisions read: throttling-strategy.md, redis-usage.md
+  Gaps: none
+  Questions: none
+
+Next step: /nova-spec
+```
+
+No code yet. The agent has classified the work, created the branch, and pulled in only the architectural decisions that matter for this ticket. From here you'd move on to `/nova-spec` to close requirements, then `/nova-plan`, then `/nova-build`.
+
+## Flow
+
+```
+/nova-start → /nova-spec → /nova-plan → /nova-build → /nova-review → /nova-wrap
+```
+
+| Command | What it does |
+|---|---|
+| `/nova-init` | One-off bootstrap: scans the repo and generates draft `context/services/` files with TODOs |
+| `/nova-start <TICKET>` | Pulls the ticket, classifies it (quick-fix / feature / architecture), creates a branch, loads context |
+| `/nova-spec` | Closes open decisions and writes `proposal.md` |
+| `/nova-plan` | Translates the spec into `tasks.md` (plan + tasks) |
+| `/nova-build` | Executes tasks one by one with incremental review |
+| `/nova-review` | Final code review against spec, conventions and decisions |
+| `/nova-wrap` | Updates memory, archives the spec, creates commit and PR |
+| `/nova-status [TICKET]` | Current status of the ticket (read-only) |
+
+`quick-fix` tickets skip `/nova-spec` and `/nova-plan`. `/nova-init` is optional and runs only once when installing nova-spec into an existing repo.
+
+## Principles
+
+- **No skipping steps.** Each command has a guardrail that checks preconditions.
+- **No making up context.** If info is missing, the command asks.
+- **Human checkpoints** after `/nova-spec` and before `/nova-wrap`.
+- **Memory that doesn't decay:** one fact = one file, name = index, explicit supersede.
+
+## Documentation
+
+- Detailed install: [INSTALL.md](./INSTALL.md)
+- Internal architecture: [novaspec/README.arch.md](./novaspec/README.arch.md)
+- Quick reference: [novaspec/README.quickref.md](./novaspec/README.quickref.md)
+- Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## See also
+
+`nova-spec` was built using itself. The full development history — including specs, decisions, gotchas and dogfooding — is preserved in the lab repo: [adansuku/nova-spec-lab](https://github.com/adansuku/nova-spec-lab).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/nova-spec.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { run } = require('../lib/cli.js');
+
+run().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/lib/cli.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { init } = require('./installer.js');
+const { sync } = require('./sync.js');
+
+async function run() {
+  const command = process.argv[2];
+
+  switch (command) {
+    case 'init':
+    case undefined:
+      await init();
+      break;
+    case 'sync':
+      await sync();
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.error('Usage: nova-spec [init|sync]');
+      process.exit(1);
+  }
+}
+
+module.exports = { run };

package/lib/installer.js

@@ -0,0 +1,243 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { select, input, confirm } = require('@inquirer/prompts');
+const { generateManifest } = require('./sync.js');
+
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const NOVASPEC_SRC = path.join(PACKAGE_ROOT, 'novaspec');
+const AGENTS_SRC = path.join(PACKAGE_ROOT, 'AGENTS.md');
+const CLAUDE_MD_SRC = path.join(PACKAGE_ROOT, 'CLAUDE.md');
+
+async function init() {
+  console.log('\n  nova-spec installer\n  ───────────────────\n');
+
+  // 1. Scope: global or project
+  const scope = await select({
+    message: 'Where do you want to install nova-spec?',
+    choices: [
+      { name: 'This project only  (installs in current directory)', value: 'project' },
+      { name: 'Global  (works in all your projects via ~/.claude)', value: 'global' },
+      { name: 'Update existing installation', value: 'update' },
+    ],
+  });
+
+  const destDir = scope === 'global'
+    ? path.join(process.env.HOME || process.env.USERPROFILE, '.claude')
+    : process.cwd();
+
+  if (scope === 'update') {
+    const { sync } = require('./sync.js');
+    await sync(destDir);
+    return;
+  }
+
+  // 2. Runtime
+  const runtime = await select({
+    message: 'Which AI runtime do you use?',
+    choices: [
+      { name: 'Claude Code', value: 'claude' },
+      { name: 'OpenCode', value: 'opencode' },
+      { name: 'Both', value: 'both' },
+    ],
+  });
+
+  // 3. Jira
+  const useJira = await confirm({ message: 'Do you use Jira?', default: true });
+
+  let jiraConfig = { skill: '', url: '', project: '', email: '', token: '${JIRA_API_TOKEN}', done_transition_id: '41' };
+
+  if (useJira) {
+    jiraConfig.skill = 'jira-integration';
+    jiraConfig.url = await input({
+      message: 'Jira URL:',
+      default: 'https://your-workspace.atlassian.net',
+    });
+    jiraConfig.project = await input({ message: 'Jira project key:', default: 'PROJ' });
+    jiraConfig.email = await input({ message: 'Your Jira email:' });
+    jiraConfig.done_transition_id = await input({
+      message: 'Jira "Done" transition ID (find it via GET /rest/api/3/issue/<TICKET>/transitions):',
+      default: '41',
+    });
+    console.log('\n  Tip: set JIRA_API_TOKEN in your environment.');
+    console.log('  Get your token at: https://id.atlassian.com/manage-profile/security/api-tokens\n');
+  }
+
+  // 4. Branch config
+  const baseBranch = await input({ message: 'Base branch:', default: 'main' });
+
+  // 5. Confirm
+  console.log('\n  Summary:');
+  console.log(`  → Scope:   ${scope === 'global' ? 'Global (~/.claude)' : 'Project (' + destDir + ')'}`);
+  console.log(`  → Runtime: ${runtime}`);
+  console.log(`  → Jira:    ${useJira ? jiraConfig.url + ' / ' + jiraConfig.project : 'disabled'}`);
+  console.log(`  → Branch:  ${baseBranch}\n`);
+
+  const ok = await confirm({ message: 'Install with these settings?', default: true });
+  if (!ok) {
+    console.log('  Cancelled.');
+    return;
+  }
+
+  // 6. Install
+  installFiles(destDir, runtime, scope);
+  writeConfig(destDir, { jiraConfig, baseBranch });
+  generateManifest(path.join(destDir, 'novaspec'));
+
+  console.log('\n  ✓ nova-spec installed!\n');
+  console.log('  Next step: open Claude Code or OpenCode in this directory and run:');
+  console.log('    /nova-start TICKET-123\n');
+}
+
+function installFiles(destDir, runtime, scope) {
+  // Copy novaspec/
+  const destNovaspec = path.join(destDir, 'novaspec');
+  const destNovaspecConfig = path.join(destNovaspec, 'config.yml');
+
+  // Backup existing config.yml
+  let configBackup = null;
+  if (fs.existsSync(destNovaspecConfig)) {
+    configBackup = fs.readFileSync(destNovaspecConfig, 'utf8');
+  }
+
+  copyDir(NOVASPEC_SRC, destNovaspec);
+
+  // Restore config.yml if it existed (user's config wins)
+  if (configBackup) {
+    fs.writeFileSync(destNovaspecConfig, configBackup);
+  }
+
+  // Copy AGENTS.md and CLAUDE.md
+  if (fs.existsSync(AGENTS_SRC)) fs.copyFileSync(AGENTS_SRC, path.join(destDir, 'AGENTS.md'));
+  if (fs.existsSync(CLAUDE_MD_SRC)) fs.copyFileSync(CLAUDE_MD_SRC, path.join(destDir, 'CLAUDE.md'));
+
+  // Create context/ structure (only for project scope)
+  if (scope === 'project') {
+    for (const dir of [
+      'context/decisions/archived',
+      'context/gotchas',
+      'context/services',
+      'context/changes/active',
+      'context/changes/archive',
+    ]) {
+      fs.mkdirSync(path.join(destDir, dir), { recursive: true });
+    }
+    const gitkeep = path.join(destDir, 'context/changes/active/.gitkeep');
+    if (!fs.existsSync(gitkeep)) fs.writeFileSync(gitkeep, '');
+
+    // notes.md
+    const notes = path.join(destDir, 'notes.md');
+    if (!fs.existsSync(notes)) fs.writeFileSync(notes, '');
+  }
+
+  // Runtime symlinks / .opencode settings
+  if (runtime === 'claude' || runtime === 'both') {
+    createSymlinks(destDir, '.claude');
+  }
+  if (runtime === 'opencode' || runtime === 'both') {
+    createSymlinks(destDir, '.opencode');
+    writeOpenCodeSettings(path.join(destDir, '.opencode'));
+  }
+
+  // .gitignore
+  ensureGitignore(destDir);
+}
+
+function createSymlinks(destDir, dotDir) {
+  const dir = path.join(destDir, dotDir);
+  fs.mkdirSync(dir, { recursive: true });
+  for (const name of ['commands', 'skills', 'agents']) {
+    const link = path.join(dir, name);
+    const target = path.join('..', 'novaspec', name);
+    if (fs.existsSync(link) || fs.lstatSync(link).isSymbolicLink?.()) {
+      fs.rmSync(link, { recursive: true, force: true });
+    }
+    fs.symlinkSync(target, link);
+  }
+}
+
+function writeOpenCodeSettings(opencodeDir) {
+  const settingsPath = path.join(opencodeDir, 'settings.local.json');
+  if (!fs.existsSync(settingsPath)) {
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      $schema: 'https://opencode.ai/config.json',
+      permission: { skill: { '*': 'allow' } },
+    }, null, 2) + '\n');
+  }
+}
+
+function writeConfig(destDir, { jiraConfig, baseBranch }) {
+  const configPath = path.join(destDir, 'novaspec', 'config.yml');
+  if (fs.existsSync(configPath)) return; // already restored from backup
+
+  const content = [
+    '# nova-spec — project configuration',
+    '# This file is gitignored — do not push it to the repo.',
+    '',
+    'branch:',
+    '  pattern: "{type}/{ticket}-{slug}"',
+    '  types:',
+    '    bugfix: bugfix',
+    '    hotfix: hotfix',
+    '    feature: feature',
+    '    documentation: docs',
+    '    refactor: refactor',
+    '    chore: chore',
+    '    architecture: arch',
+    '  ticket_case: upper',
+    `  base: ${baseBranch}`,
+    '',
+    'jira:',
+    `  skill: "${jiraConfig.skill}"`,
+    `  url: ${jiraConfig.url}`,
+    `  project: ${jiraConfig.project}`,
+    `  email: ${jiraConfig.email}`,
+    `  token: ${jiraConfig.token}`,
+    `  done_transition_id: "${jiraConfig.done_transition_id}"`,
+  ].join('\n') + '\n';
+
+  fs.writeFileSync(configPath, content);
+}
+
+function ensureGitignore(destDir) {
+  const gitignorePath = path.join(destDir, '.gitignore');
+  const marker = '# nova-spec (local)';
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (content.includes(marker)) return;
+  }
+
+  const block = [
+    '',
+    '# nova-spec (local)',
+    'novaspec/config.yml',
+    'novaspec/custom/',
+    '.env',
+    'notes.md',
+    '.opencode/settings.local.json',
+    '.opencode/node_modules/',
+    '.DS_Store',
+    '# /nova-spec',
+    '',
+  ].join('\n');
+
+  fs.appendFileSync(gitignorePath, block);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.name === 'config.yml') continue; // never overwrite user config
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = { init };

package/lib/sync.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const MANIFEST_FILE = '.nova-manifest.json';
+
+function hashFile(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+function walkDir(dir, base = dir) {
+  const results = {};
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(base, fullPath);
+    if (entry.isDirectory()) {
+      Object.assign(results, walkDir(fullPath, base));
+    } else {
+      results[relPath] = hashFile(fullPath);
+    }
+  }
+  return results;
+}
+
+function generateManifest(novaspecDir) {
+  const coreDir = novaspecDir;
+  const hashes = {};
+
+  for (const section of ['commands', 'skills', 'agents']) {
+    const sectionDir = path.join(coreDir, section);
+    if (!fs.existsSync(sectionDir)) continue;
+    for (const entry of fs.readdirSync(sectionDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() && !entry.name.endsWith('.md')) continue;
+      const name = entry.name.replace('.md', '');
+      const fullPath = path.join(sectionDir, entry.name);
+      if (entry.isDirectory()) {
+        hashes[`${section}/${name}`] = walkDir(fullPath);
+      } else {
+        hashes[`${section}/${name}`] = hashFile(fullPath);
+      }
+    }
+  }
+
+  const manifest = {
+    version: require('../package.json').version,
+    generated_at: new Date().toISOString(),
+    hashes,
+    outdated_customs: [],
+  };
+
+  const manifestPath = path.join(novaspecDir, MANIFEST_FILE);
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  return manifest;
+}
+
+async function sync(destDir = process.cwd()) {
+  const novaspecDest = path.join(destDir, 'novaspec');
+  const manifestPath = path.join(novaspecDest, MANIFEST_FILE);
+
+  if (!fs.existsSync(novaspecDest)) {
+    console.error('  ✗ nova-spec not installed in this directory. Run: npx nova-spec init');
+    process.exit(1);
+  }
+
+  // Read existing manifest
+  const oldManifest = fs.existsSync(manifestPath)
+    ? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    : { hashes: {} };
+
+  // Update core files from package
+  const PACKAGE_ROOT = path.join(__dirname, '..');
+  const NOVASPEC_SRC = path.join(PACKAGE_ROOT, 'novaspec');
+
+  // Backup config.yml
+  const configPath = path.join(novaspecDest, 'config.yml');
+  let configBackup = null;
+  if (fs.existsSync(configPath)) {
+    configBackup = fs.readFileSync(configPath, 'utf8');
+  }
+
+  copyDirSync(NOVASPEC_SRC, novaspecDest);
+
+  // Restore config
+  if (configBackup) fs.writeFileSync(configPath, configBackup);
+
+  // Regenerate manifest with new hashes
+  const newManifest = generateManifest(novaspecDest);
+
+  // Check custom overrides
+  const customDir = path.join(novaspecDest, 'custom');
+  const outdated = [];
+
+  if (fs.existsSync(customDir)) {
+    for (const section of ['commands', 'skills', 'agents']) {
+      const customSection = path.join(customDir, section);
+      if (!fs.existsSync(customSection)) continue;
+      for (const entry of fs.readdirSync(customSection, { withFileTypes: true })) {
+        const name = entry.name.replace('.md', '');
+        const key = `${section}/${name}`;
+        const oldHash = oldManifest.hashes[key];
+        const newHash = newManifest.hashes[key];
+        if (oldHash && newHash && JSON.stringify(oldHash) !== JSON.stringify(newHash)) {
+          outdated.push(name);
+        }
+      }
+    }
+  }
+
+  // Save outdated list in manifest
+  newManifest.outdated_customs = outdated;
+  fs.writeFileSync(manifestPath, JSON.stringify(newManifest, null, 2) + '\n');
+
+  // Report
+  console.log('\n  ✓ nova-spec core updated to v' + newManifest.version + '\n');
+
+  if (outdated.length > 0) {
+    console.log('  ⚠️  Custom overrides with upstream changes:');
+    for (const name of outdated) {
+      console.log(`     - ${name} → run /nova-diff ${name} to review`);
+    }
+  } else {
+    console.log('  ✓ No custom overrides affected.');
+  }
+  console.log('');
+}
+
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === 'config.yml') continue;
+    if (entry.name === 'custom') continue; // never overwrite custom/
+    if (entry.name === MANIFEST_FILE) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = { sync, generateManifest };

package/novaspec/agents/context-loader.md

@@ -0,0 +1,65 @@
+---
+description: Load architectural context in an isolated context window and return a structured summary
+argument-hint: <service1> [service2 ...]
+---
+
+You are a context-loading agent. Your only job is to read the artifacts of
+the given services and return a structured summary. Don't interact with
+the user beyond the final summary. Don't modify any file.
+
+## Input
+
+Affected services: `$ARGUMENTS` (space-separated list)
+
+## Hard rules
+
+- **Never read `context/decisions/archived/`**. It's a trash bin; its content is explicitly out of the live scope.
+- **Total budget: ≤3000 tokens**. If summing the chosen files gets close to the cap, trim by relevance. Don't load all of `decisions/` — only the 3-5 files whose names match the ticket scope.
+- Don't write any file.
+- Don't make up context.
+
+## Steps
+
+### 1. Verify `context/`
+
+If `context/` doesn't exist, return:
+```
+## Loaded context
+**Services**: not documented (context/ missing)
+**Decisions**: none
+**Gaps**: context/ structure not initialized — run install.sh
+**Questions**: none
+```
+And stop.
+
+### 2. Read each service
+
+For each service in `$ARGUMENTS`:
+- Read `context/services/<service>.md` if it exists.
+- If it doesn't exist, note it as a gap.
+
+### 3. Pick relevant decisions and gotchas
+
+- `ls context/decisions/` (no `-R`, doesn't enter `archived/`).
+- `ls context/gotchas/`.
+- Pick 3-5 files from each whose name is relevant to the ticket's scope or affected services. Don't force connections.
+- Read the chosen ones.
+
+### 4. Return summary
+
+Return exactly this structure, without extra text:
+
+```
+## Loaded context
+
+**Services**: <list with ✓ if services/<svc>.md exists, ✗ otherwise>
+**Decisions read**: <list of files or "none">
+**Gotchas read**: <list of files or "none">
+**Gaps**: <missing files or "none">
+**Questions**: <detected ambiguities or "none">
+```
+
+## Rules (reminder)
+
+- Don't block if documentation is missing; report it under Gaps.
+- Return only the `## Loaded context` block.