graphify-openspec-bridge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 klc
+
+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,148 @@
+# graphify-openspec-bridge
+
+**OpenSpec + Graphify = codebase-aware AI workflow.**
+
+Bridge your OpenSpec change proposals with your codebase's knowledge graph. Every artifact—proposal, specs, design, tasks—is grounded in real code structure instead of guesswork.
+
+```mermaid
+flowchart LR
+    A[OpenSpec Change] --> B[graphify-augmented Schema]
+    B --> C[Graphify Query]
+    C --> D[Knowledge Graph]
+    D --> E[Code-aware Artifacts]
+    E --> F[Better AI Output]
+```
+
+## Features
+
+- **Graphify-first workflow** — 5-artifact pipeline: proposal → explore → specs → design → tasks
+- **Exploration step** — dedicated artifact for graphify query results before design
+- **CLI diagnostics** — check runtime, dependency, and project health
+- **Zero-config install** — single command copies schema + configures OpenSpec
+
+## Install
+
+### One-liner
+
+```bash
+npx graphify-openspec-bridge install ./my-project --with-config
+```
+
+### Global install
+
+```bash
+npm install -g graphify-openspec-bridge
+
+# Alias: gob
+gob install ./my-project --with-config
+```
+
+### Prerequisites
+
+| Tool | Install |
+|------|---------|
+| [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec) | `npm install -g @fission-ai/openspec` |
+| [Graphify](https://github.com/safishamsi/graphify) | `pipx install graphifyy` |
+| Node.js 16+ | `node --version` |
+
+## Quick Start
+
+```bash
+# 1. Check your project is ready
+gob check
+
+# 2. Install the graphify-augmented schema
+gob install --with-config
+
+# 3. Validate
+gob validate
+
+# 4. Start a codebase-aware change
+openspec new change my-feature --schema graphify-augmented
+
+# 5. Before writing the proposal, explore your codebase
+openspec new artifact explore  # runs graphify query/path/explain
+```
+
+## CLI Reference
+
+### `check [path]`
+
+Check runtime (Node.js), dependencies (OpenSpec, Graphify), and project state (config, schema, graph).
+
+```bash
+gob check ~/my-project
+```
+
+Output:
+
+```
+  Runtime
+    ✓ Node.js v24.12.0
+
+  Dependencies
+    ✓ openspec 1.3.1
+    ✓ graphify 0.8.19
+
+  Project
+    ✓ openspec/config.yaml
+    ✓ openspec/schemas/graphify-augmented/  (schema.yaml + 5 templates)
+    ✓ graphify-out/graph.json  (2304 nodes, 2408 edges)
+
+Status: Ready
+```
+
+### `install [path] [--with-config]`
+
+Copy the `graphify-augmented` schema to a project's `openspec/schemas/` directory.
+
+| Flag | Effect |
+|------|--------|
+| `--with-config` | Also update `openspec/config.yaml` with graphify context + rules |
+
+### `validate`
+
+Run `openspec schema validate graphify-augmented` to verify the schema is correctly installed.
+
+### `version`
+
+Print package version.
+
+### `help`
+
+Show usage information.
+
+## Schema: graphify-augmented
+
+The schema follows this workflow:
+
+```
+proposal (why) → explore (graph) → specs (what) → design (how) → tasks (do)
+```
+
+| Artifact | Description | Graphify Usage |
+|----------|-------------|----------------|
+| **proposal** | Business motivation, capabilities | `graphify query <domain>` for codebase context |
+| **explore** | Knowledge graph deep-dive | `query` + `path` + `explain` — maps affected areas |
+| **specs** | Detailed requirements | References exploration findings |
+| **design** | Technical architecture | `graphify path` to verify connections |
+| **tasks** | Implementation checklist | Tasks annotated with graph node references |
+| **apply** | Execute tasks | Auto-runs `graphify update .` on completion |
+
+## Development
+
+```bash
+git clone https://github.com/klc/graphify-openspec-bridge
+cd graphify-openspec-bridge
+npm link
+gob check
+```
+
+## Related
+
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — AI-native spec-driven development
+- [Graphify](https://github.com/safishamsi/graphify) — turn any folder into a queryable knowledge graph
+
+## License
+
+MIT

package/bin/graphify-openspec-bridge.js

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const os = require('os');
+
+// ── Config ──────────────────────────────────────────────────────────────────
+const PKG = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+);
+const VERSION = PKG.version;
+const NAME = PKG.name;
+const SCHEMA_DIR = 'openspec/schemas/graphify-augmented';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function color(code, s) {
+  // Skip color if piped or NO_COLOR
+  if (!process.stdout.isTTY || process.env.NO_COLOR) return s;
+  return `\x1b[${code}m${s}\x1b[0m`;
+}
+const green  = s => color('32', s);
+const red    = s => color('31', s);
+const yellow = s => color('33', s);
+const dim    = s => color('90', s);
+const bold   = s => color('1', s);
+
+function which(name) {
+  // `which` on Unix, `where` on Windows
+  const cmd = os.platform() === 'win32' ? 'where' : 'which';
+  try {
+    const out = execSync(`${cmd} ${name}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    return out.split('\n')[0]; // first match
+  } catch {
+    return null;
+  }
+}
+
+function execVersion(name, args = ['--version']) {
+  try {
+    return execSync(`${name} ${args.join(' ')}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function resolveTarget(targetPath) {
+  return targetPath ? path.resolve(targetPath) : process.cwd();
+}
+
+// ── Check logic ─────────────────────────────────────────────────────────────
+
+function checkRuntime() {
+  const v = process.versions.node;
+  const major = parseInt(v.split('.')[0], 10);
+  const ok = major >= 16;
+  return { name: 'Node.js', version: `v${v}`, ok };
+}
+
+function checkTool(name) {
+  const loc = which(name);
+  if (!loc) return { name, ok: false, version: null, path: null };
+  let version = null;
+  try {
+    version = execVersion(name);
+  } catch { /* ignore */ }
+  return { name, ok: true, version: version || '?', path: loc };
+}
+
+function checkProject(targetPath) {
+  const results = [];
+
+  // config.yaml
+  const configPath = path.join(targetPath, 'openspec', 'config.yaml');
+  const hasConfig = fs.existsSync(configPath);
+  results.push({
+    label: 'openspec/config.yaml',
+    ok: hasConfig,
+    detail: hasConfig ? 'exists' : 'missing — run openspec init'
+  });
+
+  // Schema installed
+  const schemaPath = path.join(targetPath, 'openspec', 'schemas', 'graphify-augmented', 'schema.yaml');
+  const hasSchema = fs.existsSync(schemaPath);
+  const templatesDir = path.join(targetPath, 'openspec', 'schemas', 'graphify-augmented', 'templates');
+  const templateCount = fs.existsSync(templatesDir)
+    ? fs.readdirSync(templatesDir).filter(f => f.endsWith('.md')).length
+    : 0;
+  results.push({
+    label: `openspec/schemas/graphify-augmented/`,
+    ok: hasSchema && templateCount === 5,
+    detail: hasSchema
+      ? `schema.yaml + ${templateCount} templates`
+      : 'schema not installed'
+  });
+
+  // graphify-out/graph.json
+  const graphPath = path.join(targetPath, 'graphify-out', 'graph.json');
+  const hasGraph = fs.existsSync(graphPath);
+  let graphDetail = 'not found — run /graphify .';
+  if (hasGraph) {
+    try {
+      const g = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
+      const nodes = g.nodes ? g.nodes.length : '?';
+      const edges = g.links ? g.links.length : '?';
+      graphDetail = `${nodes} nodes, ${edges} edges`;
+    } catch {
+      graphDetail = 'exists (parse error)';
+    }
+  }
+  results.push({
+    label: 'graphify-out/graph.json',
+    ok: hasGraph,
+    detail: graphDetail
+  });
+
+  return results;
+}
+
+// ── Commands ────────────────────────────────────────────────────────────────
+
+function cmdCheck(argv) {
+  const target = resolveTarget(argv[0]);
+
+  console.log('');
+  console.log(bold(`${NAME} v${VERSION} — check`));
+  console.log('');
+
+  // Runtime
+  const rt = checkRuntime();
+  console.log(`  ${bold('Runtime')}`);
+  console.log(`    ${rt.ok ? green('✓') : red('✗')} ${rt.name} ${dim(rt.version)}`);
+  console.log('');
+
+  // Dependencies
+  console.log(`  ${bold('Dependencies')}`);
+  const deps = ['openspec', 'graphify'].map(checkTool);
+  for (const d of deps) {
+    const icon = d.ok ? green('✓') : red('✗');
+    const hint = d.ok ? dim(d.path) : dim(`install: ${d.name === 'graphify' ? 'pipx install graphifyy' : 'npm install -g @fission-ai/openspec'}`);
+    console.log(`    ${icon} ${d.name} ${d.version ? dim(d.version) : ''}  ${hint}`);
+  }
+  console.log('');
+
+  // Project
+  const projectExists = fs.existsSync(path.join(target, 'openspec'));
+  if (projectExists) {
+    console.log(`  ${bold('Project')} ${dim(target)}`);
+    const checks = checkProject(target);
+    for (const c of checks) {
+      const icon = c.ok ? green('✓') : red('✗');
+      console.log(`    ${icon} ${c.label} ${dim(c.detail)}`);
+    }
+  } else {
+    console.log(`  ${yellow('⚠')} ${bold('Project')} ${dim(target)}`);
+    console.log(`    ${dim('not an OpenSpec project — run openspec init')}`);
+  }
+
+  // Summary
+  const allOk = rt.ok && deps.every(d => d.ok) && projectExists && checkProject(target).every(c => c.ok);
+  console.log('');
+  console.log(allOk ? green('Status: Ready') : yellow('Status: Needs attention'));
+  console.log('');
+  process.exit(allOk ? 0 : 1);
+}
+
+function cmdInstall(argv) {
+  const target = resolveTarget(argv[0]);
+  const withConfig = argv.includes('--with-config');
+
+  console.log('');
+  console.log(bold(`${NAME} v${VERSION} — install`));
+  console.log(`  ${dim('Target: ' + target)}`);
+  console.log('');
+
+  // Source schema directory (within this package)
+  const srcSchema = path.join(__dirname, '..', SCHEMA_DIR);
+  const dstSchema = path.join(target, 'openspec', 'schemas', 'graphify-augmented');
+
+  if (!fs.existsSync(srcSchema)) {
+    console.log(`  ${red('✗')} Schema source not found: ${srcSchema}`);
+    console.log('');
+    process.exit(1);
+  }
+
+  // Create target directory
+  fs.mkdirSync(dstSchema, { recursive: true });
+  fs.mkdirSync(path.join(dstSchema, 'templates'), { recursive: true });
+
+  // Copy schema.yaml
+  try {
+    fs.copyFileSync(
+      path.join(srcSchema, 'schema.yaml'),
+      path.join(dstSchema, 'schema.yaml')
+    );
+  } catch (e) {
+    console.log(`  ${red('✗')} Failed to copy schema.yaml: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Copy templates
+  const srcTemplates = path.join(srcSchema, 'templates');
+  const dstTemplates = path.join(dstSchema, 'templates');
+  const templates = fs.readdirSync(srcTemplates).filter(f => f.endsWith('.md'));
+  let copied = 1; // schema.yaml
+  for (const t of templates) {
+    try {
+      fs.copyFileSync(path.join(srcTemplates, t), path.join(dstTemplates, t));
+      copied++;
+    } catch (e) {
+      console.log(`  ${yellow('⚠')} Failed to copy ${t}: ${e.message}`);
+    }
+  }
+
+  console.log(`  ${green('✓')} Schema files copied (${copied} files)`);
+  console.log(`    ${dim(dstSchema)}`);
+  console.log('');
+
+  // --with-config
+  if (withConfig) {
+    const configPath = path.join(target, 'openspec', 'config.yaml');
+
+    // Backup existing
+    if (fs.existsSync(configPath)) {
+      const bak = configPath + '.bak';
+      try {
+        fs.copyFileSync(configPath, bak);
+        console.log(`  ${green('✓')} Backup: config.yaml → config.yaml.bak`);
+      } catch (e) {
+        console.log(`  ${yellow('⚠')} Backup failed: ${e.message}`);
+      }
+    }
+
+    const contextBlock = `context: |
+  This project uses graphify knowledge graph for codebase awareness.
+  Graph file: graphify-out/graph.json
+  GRAPH_REPORT.md: graphify-out/GRAPH_REPORT.md
+  Interactive viz: graphify-out/graph.html
+
+  Commands:
+    graphify query "<question>"  - BFS traversal, broad context
+    graphify path "<A>" "<B>"    - shortest path between concepts
+    graphify explain "<node>"    - deep-dive on a node
+
+rules:
+  proposal:
+    - Run \`graphify query "<domain>"\` BEFORE writing proposal
+    - Include Graph Context section with god nodes and communities
+  explore:
+    - Run ALL three: graphify query, graphify path, graphify explain
+    - Document confidence tags for each edge
+  specs:
+    - Reference exploration.md findings when defining requirements
+  design:
+    - Run \`graphify path\` to verify architectural connections
+  tasks:
+    - Annotate tasks with graph nodes: [Node: NodeName]
+`;
+
+    // Check if config exists and has schema line
+    const configContent = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';
+    const hasSchemaLine = configContent.includes('schema:');
+
+    let newConfig = '';
+    if (hasSchemaLine) {
+      // Replace schema line, append context
+      newConfig = configContent.replace(/^schema:.*$/m, 'schema: graphify-augmented');
+      // Append context if not already there
+      if (!configContent.includes('graphify knowledge graph')) {
+        newConfig += '\n' + contextBlock;
+      }
+    } else {
+      newConfig = 'schema: graphify-augmented\n\n' + contextBlock;
+    }
+
+    try {
+      fs.writeFileSync(configPath, newConfig, 'utf8');
+      console.log(`  ${green('✓')} config.yaml updated (schema: graphify-augmented + context + rules)`);
+    } catch (e) {
+      console.log(`  ${red('✗')} Failed to update config.yaml: ${e.message}`);
+    }
+    console.log('');
+  }
+
+  // Summary
+  console.log(`  ${green('✓')} Install complete`);
+  console.log('');
+  console.log(`  ${bold('Next steps:')}`);
+  console.log(`    openspec schema validate graphify-augmented`);
+  console.log(`    openspec new change <name> --schema graphify-augmented`);
+  console.log('');
+}
+
+function cmdValidate() {
+  console.log('');
+  console.log(bold(`${NAME} v${VERSION} — validate`));
+  console.log('');
+
+  const openspecPath = which('openspec');
+  if (!openspecPath) {
+    console.log(`  ${red('✗')} OpenSpec CLI not found`);
+    console.log(`  ${dim('Install: npm install -g @fission-ai/openspec')}`);
+    console.log('');
+    process.exit(1);
+  }
+
+  try {
+    const out = execSync('openspec schema validate graphify-augmented', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    console.log(out.trim());
+    console.log('');
+    console.log(`  ${green('✓')} Schema is valid`);
+    console.log('');
+  } catch (e) {
+    console.log(`  ${red('✗')} Validation failed:`);
+    console.log(`  ${dim(e.stderr ? e.stderr.trim() : e.message)}`);
+    console.log('');
+    process.exit(1);
+  }
+}
+
+function cmdHelp() {
+  console.log(`
+${bold(NAME)} v${VERSION}
+
+Bridge between OpenSpec and Graphify — codebase-aware OpenSpec workflow.
+
+${bold('Usage:')}
+  ${dim('graphify-openspec-bridge')} ${green('<command>')} ${yellow('[options]')}
+  ${dim('gob')} ${green('<command>')} ${yellow('[options]')}
+
+${bold('Commands:')}
+  ${green('check')}    ${yellow('[path]')}         Check runtime, deps, and project state
+  ${green('install')}  ${yellow('[path]')} ${yellow('[--with-config]')}  Install schema to project
+  ${green('validate')}                Validate schema installation
+  ${green('version')}                 Show version
+  ${green('help')}                    Show this help
+
+${bold('Examples:')}
+  ${dim('# Check current project')}
+  gob check
+
+  ${dim('# Check specific project')}
+  gob check ~/my-project
+
+  ${dim('# Install schema')}
+  gob install ~/my-project
+
+  ${dim('# Install with config update')}
+  gob install ~/my-project --with-config
+
+  ${dim('# Validate schema')}
+  gob validate
+
+${bold('Docs:')} https://github.com/klc/graphify-openspec-bridge
+`);
+}
+
+function cmdVersion() {
+  console.log(`${NAME} v${VERSION}`);
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const cmd = args[0] || 'help';
+
+switch (cmd) {
+  case 'check':
+    cmdCheck(args.slice(1));
+    break;
+  case 'install':
+    cmdInstall(args.slice(1));
+    break;
+  case 'validate':
+    cmdValidate();
+    break;
+  case 'version':
+  case '--version':
+  case '-v':
+    cmdVersion();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  default:
+    cmdHelp();
+    break;
+}

package/openspec/schemas/graphify-augmented/schema.yaml

@@ -0,0 +1,170 @@
+name: graphify-augmented
+version: 1
+description: Graphify-augmented workflow - every artifact grounded in your codebase's knowledge graph. Adds an explore step between proposal and design for codebase-aware specs, designs, and tasks.
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: |
+      Before writing the proposal, run `graphify query "<domain>"` to understand the codebase landscape relevant to this change. Find the god nodes and communities that this change will affect.
+
+      Then create the proposal document that establishes WHY this change is needed.
+
+      Sections:
+      - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+      - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+      - **Capabilities**: Identify which specs will be created or modified:
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
+        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
+      - **Graph Context**: Summarize key graphify findings - which communities, god nodes, and code areas are relevant
+      - **Impact**: Affected code, APIs, dependencies, or systems
+
+      IMPORTANT: The Capabilities section is critical. It creates the contract between
+      proposal and specs phases. Research existing specs before filling this in.
+      Each capability listed here will need a corresponding spec file.
+
+      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+      implementation details belong in design.md.
+
+      This is the foundation - specs, design, and tasks all build on this.
+    requires: []
+
+  - id: explore
+    generates: exploration.md
+    description: Graphify exploration of relevant codebase areas
+    template: explore.md
+    instruction: |
+      Run graphify queries to map the codebase areas affected by this change. This artifact captures the knowledge graph exploration results that subsequent artifacts will reference.
+
+      Required graphify commands (run each and document results):
+
+      1. **`graphify query "<change domain>"`** - Broad context. Find god nodes, relevant communities, and all code areas related to this change. Document the key nodes and their relationships.
+
+      2. **`graphify path <concept_A> <concept_B>`** - Relationship mapping. Trace connections between the main components this change touches. Document each hop with its relation and confidence level.
+
+      3. **`graphify explain <key_concept>`** - Deep dive on critical components. Document the node's degree, connections, source files, and what its neighbors reveal.
+
+      If a concept has no matching node, note that as a gap - this means the graph doesn't cover that area yet.
+
+      Document all findings in the template below. Each finding should include the source file location and confidence tag (EXTRACTED/INFERRED/AMBIGUOUS).
+    requires:
+      - proposal
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    instruction: |
+      Read exploration.md to understand the codebase context. Use the graph findings to identify all affected components, interfaces, and data flows.
+
+      Create one spec file per capability listed in the proposal's Capabilities section.
+      - New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
+      - Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+      - Every requirement MUST have at least one scenario.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in openspec/specs/<capability>/spec.md
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+
+      Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+      If adding new concerns without changing existing behavior, use ADDED instead.
+
+      Specs should be testable - each scenario is a potential test case.
+    requires:
+      - proposal
+      - explore
+
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    instruction: |
+      Reference exploration.md for codebase relationships. Run graphify queries to verify architectural understanding before writing.
+
+      Before writing, optionally run:
+      - `graphify path <component_A> <component_B>` to verify how two components connect
+      - `graphify explain <key_component>` to deep-dive on critical modules
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections:
+      - **Context**: Background, current state, constraints, stakeholders. Reference graph communities from exploration.md.
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes
+      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+      - **Graph Verification**: How graphify queries confirmed (or challenged) architectural assumptions
+      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+      - **Open Questions**: Outstanding decisions or unknowns to resolve
+
+      Focus on architecture and approach, not line-by-line implementation.
+      Reference the proposal for motivation and specs for requirements.
+    requires:
+      - explore
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    instruction: |
+      Create the task list that breaks down the implementation work. Each task should reference the graph nodes and source files identified in exploration.md.
+
+      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+
+      Guidelines:
+      - Group related tasks under ## numbered headings
+      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Tasks should be small enough to complete in one session
+      - Order tasks by dependency (what must be done first?)
+      - If applicable, annotate tasks with the graph nodes they affect: `[Node: NodeName]`
+
+      Example:
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure [Node: ModuleStructure]
+      - [ ] 1.2 Add dependencies to package.json
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function [Node: DataExportService]
+      - [ ] 2.2 Add CSV formatting utilities
+      ```
+
+      Reference specs for what needs to be built, design for how to build it.
+      Each task should be verifiable - you know when it's done.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read context files, work through pending tasks, mark complete as you go.
+    Pause if you hit blockers or need clarification.
+
+    After all tasks are complete, ALWAYS run `graphify update .` to keep the
+    knowledge graph current with the new code. This ensures future artifacts
+    see the latest codebase structure.

package/openspec/schemas/graphify-augmented/templates/design.md

@@ -0,0 +1,27 @@
+## Context
+
+<!-- Background and current state. Reference graph communities from exploration.md. -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale -->
+
+## Graph Verification
+
+<!-- How graphify queries confirmed or challenged architectural assumptions.
+     Run: graphify path <component_A> <component_B> to verify connections. -->
+
+- **Verified**: <!-- connections confirmed by graph -->
+- **Challenged**: <!-- assumptions the graph contradicted -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->

package/openspec/schemas/graphify-augmented/templates/explore.md

@@ -0,0 +1,75 @@
+## Domain Overview
+
+<!--
+Run: graphify query "<change domain>"
+Document the broad codebase context: god nodes, relevant communities, key relationships.
+-->
+
+### Communities
+
+| Community | Nodes | Relevance |
+|-----------|-------|-----------|
+| <!-- community name --> | <!-- key nodes --> | <!-- why relevant --> |
+
+### God Nodes
+
+<!-- Most-connected concepts in the affected area -->
+
+| Node | Degree | Source File |
+|------|--------|-------------|
+| <!-- node name --> | <!-- degree --> | <!-- source location --> |
+
+## Path Analysis
+
+<!--
+Run: graphify path <concept_A> <concept_B>
+Trace connections between main components this change touches.
+-->
+
+### Path: <concept_A> → <concept_B>
+
+| Hop | Relation | Confidence | Source |
+|-----|----------|------------|--------|
+| <!-- node A --> | <!-- relation --> | <!-- EXTRACTED/INFERRED --> | <!-- file --> |
+| <!-- node B --> | <!-- relation --> | <!-- EXTRACTED/INFERRED --> | <!-- file --> |
+
+### Path: <concept_C> → <concept_D>
+
+<!-- Repeat for each critical path -->
+
+## Deep Dives
+
+<!--
+Run: graphify explain <key_concept>
+Deep-dive on critical components.
+-->
+
+### <Concept Name>
+
+- **Degree**: <!-- number of connections -->
+- **Type**: <!-- code/document/paper -->
+- **Source**: <!-- source file -->
+- **Connections**: <!-- key neighbors with relations -->
+
+<!-- Repeat for each key concept -->
+
+## Graph Gaps
+
+<!-- Nodes or concepts that DON'T exist in the graph.
+     This means the codebase area is not yet mapped. -->
+
+- <!-- missing concept -->
+
+## Key Findings
+
+<!-- Surprising connections, architectural insights, risks discovered via graph -->
+
+1. <!-- finding -->
+2. <!-- finding -->
+
+## Suggested Queries
+
+<!-- Questions the graph can answer for the next phases -->
+
+- `graphify query "..."` — <!-- what it reveals -->
+- `graphify path "..." "..."` — <!-- what it connects -->

package/openspec/schemas/graphify-augmented/templates/proposal.md

@@ -0,0 +1,33 @@
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now?
+     After running graphify query "<domain>", note relevant findings here. -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
+- `<name>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
+- `<existing-name>`: <what requirement is changing>
+
+## Graph Context
+
+<!-- Summarize key graphify findings that inform this proposal.
+     Which communities, god nodes, and code areas are relevant to this change? -->
+
+- **Relevant Communities**: <!-- community labels -->
+- **Key God Nodes**: <!-- node names with source files -->
+- **Critical Paths**: <!-- graphify path findings -->
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->

package/openspec/schemas/graphify-augmented/templates/spec.md

@@ -0,0 +1,10 @@
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->
+
+**Graph References:** <!-- nodes from exploration.md that relate to this requirement -->

package/openspec/schemas/graphify-augmented/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description --> <!-- [Node: NodeName] -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description --> <!-- [Node: NodeName] -->

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "graphify-openspec-bridge",
+  "version": "1.0.0",
+  "description": "Bridge between OpenSpec and Graphify - codebase-aware OpenSpec workflow with knowledge graph integration",
+  "keywords": [
+    "openspec",
+    "graphify",
+    "knowledge-graph",
+    "schema",
+    "workflow",
+    "ai-coding"
+  ],
+  "homepage": "https://github.com/klc/graphify-openspec-bridge",
+  "bugs": {
+    "url": "https://github.com/klc/graphify-openspec-bridge/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/klc/graphify-openspec-bridge.git"
+  },
+  "license": "MIT",
+  "author": "klc",
+  "type": "commonjs",
+  "main": "index.js",
+  "bin": {
+    "graphify-openspec-bridge": "bin/graphify-openspec-bridge.js",
+    "gob": "bin/graphify-openspec-bridge.js"
+  },
+  "files": [
+    "bin/",
+    "openspec/"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}