anchormd 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sultan Valiyev
+
+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,132 @@
+# AnchorMD
+
+Persistent project context for AI coding agents using linked markdown plans with relationship tracking and hybrid search.
+
+## Install
+
+```bash
+npm install -g anchormd
+```
+
+## Quick Start
+
+```bash
+# Initialize in your project
+anchormd init
+
+# Edit the project overview
+anchormd write anchor
+
+# Create a plan
+echo '---
+name: auth
+description: Authentication system
+status: planned
+---
+# Authentication
+
+JWT-based auth. See [[database]] for schema.
+Uses POST /api/auth/login endpoint.
+Config in src/auth/config.ts.
+' | anchormd write auth
+
+# View project context
+anchormd context
+
+# List all plans
+anchormd ls
+
+# Read a specific plan
+anchormd read auth
+
+# Read a specific section
+anchormd read auth#authentication
+
+# View project stats
+anchormd status
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `anchormd init [--no-qmd]` | Initialize AnchorMD in the current project |
+| `anchormd context` | Print project overview and plan summary table |
+| `anchormd write <name> [--from <file>]` | Write or update a plan (reads from file, stdin, or editor) |
+| `anchormd ls [--status <s>] [--json]` | List all plans, optionally filtered by status |
+| `anchormd read <name[#section]>` | Read a plan or a specific section via deep link |
+| `anchormd find <query> [--semantic] [--hybrid] [--limit <n>] [--json]` | Search plans (requires QMD) |
+| `anchormd reindex` | Rebuild the index graph and search database |
+| `anchormd status` | Show plan count, links, weak edges, and QMD status |
+
+## How It Works
+
+### Plans
+
+Plans are markdown files with YAML frontmatter stored in `.anchor/plans/`. Each plan has:
+
+- **name**: identifier used in links
+- **description**: short summary
+- **status**: one of `planned`, `in-progress`, `built`, `deprecated`
+- **tags**: optional array of tags
+
+### Links
+
+Plans reference each other using wiki-style links:
+
+- **Strong links**: `[[plan-name]]` creates an explicit edge in the graph
+- **Deep links**: `[[plan-name#section]]` links to a specific section
+
+### Entities
+
+AnchorMD extracts entity references from plan content:
+
+- **File paths**: `src/auth/config.ts`, `lib/utils.js`
+- **Models**: `model User`, `UserSchema`
+- **Routes**: `GET /api/users`, `POST /api/auth/login`
+- **Scripts**: `deploy.sh`, `npm run build`
+
+### Weak Edges
+
+When two plans reference the same entity (e.g., both mention `src/auth/config.ts`), AnchorMD creates a **weak edge** between them. This surfaces implicit relationships that weren't explicitly linked.
+
+### Index Graph
+
+The index graph (`.anchor/index.json`) tracks all plans, their links, entities, and weak edges. It's rebuilt automatically when plans are written, or manually via `anchormd reindex`.
+
+## Configuration
+
+Configuration is stored in `.anchor/config.json`:
+
+```json
+{
+  "qmd": false
+}
+```
+
+- **qmd**: Enable/disable QMD search integration. Set to `false` by default since QMD currently requires the Bun runtime.
+
+## Claude Code Integration
+
+AnchorMD ships with a skill file at `skill/SKILL.md` for integration with Claude Code. The skill teaches Claude to:
+
+1. Run `anchormd context` at session start
+2. Search for relevant plans before starting tasks
+3. Read plan details as needed
+4. Update plans after implementing changes
+
+## Project Structure
+
+```
+.anchor/
+  config.json       # Project configuration
+  index.json        # Relationship graph
+  search.sqlite     # QMD search database (gitignored)
+  plans/
+    anchor.md       # Project overview (created on init)
+    *.md            # Your plan files
+```
+
+## License
+
+MIT

package/bin/anchormd

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import('../src/cli.ts');

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "anchormd",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Persistent project context for AI coding agents using linked markdown plans with hybrid search",
+  "main": "src/cli.ts",
+  "bin": {
+    "anchormd": "./bin/anchormd"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --outdir dist --target bun",
+    "dev": "bun run src/cli.ts",
+    "test": "bun test"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "skill/"
+  ],
+  "keywords": [
+    "ai",
+    "cli",
+    "markdown",
+    "plans",
+    "context",
+    "coding-agent",
+    "project-management",
+    "knowledge-graph"
+  ],
+  "author": "Sultan Valiyev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sultanvaliyev/anchormd.git"
+  },
+  "dependencies": {
+    "@tobilu/qmd": "^2.0.1",
+    "commander": "^13.1.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.2.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: anchormd
+description: Persistent project context for AI coding agents using linked markdown plans
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# AnchorMD Skill
+
+You have access to AnchorMD, a project context system that gives you persistent, queryable knowledge about the project you are working on. Use it to understand the project, find relevant plans, and update context as you work.
+
+## Workflow
+
+1. **At session start**: Run `anchormd context` to load the project overview and see all plans.
+2. **Before starting a task**: Run `anchormd find "<topic>"` to find relevant plans (or `anchormd ls` to browse).
+3. **Read details**: Use `anchormd read <plan>` to get the full content of a plan. Use `anchormd read <plan>#<section>` for a specific section.
+4. **After implementing**: Update plans with `anchormd write <plan-name>` to reflect what was built.
+5. **Track progress**: Use `anchormd ls --status in-progress` to see active work items.
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `anchormd init` | Initialize AnchorMD in current project. Use `--no-qmd` to disable search. |
+| `anchormd context` | Print project overview (anchor.md) and plan summary table. |
+| `anchormd write <name>` | Write a plan. Reads from `--from <file>`, piped stdin, or opens `$EDITOR`. |
+| `anchormd ls` | List all plans. Filter with `--status <status>`. Use `--json` for structured output. |
+| `anchormd read <name>` | Read a plan. Supports `name#section` deep links. |
+| `anchormd find <query>` | Search plans. Use `--semantic`, `--hybrid`, `--limit <n>`, `--json`. |
+| `anchormd reindex` | Rebuild the index graph and search database. |
+| `anchormd status` | Show plan count, link count, weak edges, and QMD status. |
+
+## Tips
+
+- Use `--json` flag with `ls` and `find` for structured output you can parse programmatically.
+- Plans link to each other with `[[plan-name]]` syntax. Use `[[plan#section]]` for deep links.
+- The index graph tracks both explicit links and "weak edges" (plans that reference the same files, models, routes, or scripts).
+- After writing or modifying plans, the index is automatically rebuilt. Run `anchormd reindex` manually if needed.
+- Plan statuses: `planned`, `in-progress`, `built`, `deprecated`.

package/src/cli.ts

@@ -0,0 +1,362 @@
+/**
+ * AnchorMD CLI
+ *
+ * Persistent project context for AI coding agents using linked markdown plans
+ */
+
+import { Command } from 'commander';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+
+import { ensureProjectInitialized, getAnchorDir, getPlansDir } from './config.js';
+import { readPlan, writePlan, listPlans, parseFrontmatter, serializePlan } from './plan.js';
+import { rebuildAndWriteIndex, readIndex } from './index-graph.js';
+import { getQmdStore, reindexQmd, searchQmd } from './qmd.js';
+import { scaffold } from './scaffold.js';
+import { color, formatPlanTable, formatSearchResults, formatStatus } from './format.js';
+import type { PlanStatus } from './types.js';
+import { VALID_STATUSES } from './types.js';
+
+const VERSION = '0.1.0';
+
+const program = new Command();
+
+program
+  .name('anchormd')
+  .description('Persistent project context for AI coding agents using linked markdown plans')
+  .version(VERSION);
+
+// ─── init ────────────────────────────────────────────────────────────────────
+
+program
+  .command('init')
+  .description('Initialize AnchorMD in the current project')
+  .option('--no-qmd', 'Disable QMD search integration')
+  .action(async (options) => {
+    const anchorDir = path.join(process.cwd(), '.anchor');
+
+    if (existsSync(anchorDir)) {
+      console.error(color.red('Error: .anchor/ directory already exists. Project already initialized.'));
+      process.exit(1);
+    }
+
+    await scaffold(process.cwd(), { qmd: options.qmd });
+  });
+
+// ─── context ─────────────────────────────────────────────────────────────────
+
+program
+  .command('context')
+  .description('Print project overview and plan summary')
+  .action(() => {
+    const { projectRoot } = ensureProjectInitialized();
+    const plansDir = getPlansDir(projectRoot);
+
+    // Print anchor.md content
+    const anchorPath = path.join(plansDir, 'anchor.md');
+    if (existsSync(anchorPath)) {
+      const content = readFileSync(anchorPath, 'utf-8');
+      console.log(content);
+    }
+
+    // Print plan summary table
+    const plans = listPlans(plansDir);
+    console.log(color.bold('Plans:'));
+    console.log(formatPlanTable(plans));
+    console.log('');
+  });
+
+// ─── write ───────────────────────────────────────────────────────────────────
+
+program
+  .command('write <name>')
+  .description('Write or update a plan')
+  .option('--from <file>', 'Read plan content from a file')
+  .action(async (name: string, options) => {
+    const { projectRoot, config } = ensureProjectInitialized();
+    const plansDir = getPlansDir(projectRoot);
+    const anchorDir = getAnchorDir(projectRoot);
+
+    let content: string;
+
+    if (options.from) {
+      // Read from specified file
+      const fromPath = path.resolve(options.from);
+      if (!existsSync(fromPath)) {
+        console.error(color.red(`Error: File not found: ${fromPath}`));
+        process.exit(1);
+      }
+      content = readFileSync(fromPath, 'utf-8');
+    } else if (!process.stdin.isTTY) {
+      // Read from piped stdin
+      content = readFileSync(0, 'utf-8');
+    } else {
+      // Spawn editor
+      const editor = process.env.EDITOR || 'vi';
+      const tmpFile = path.join(tmpdir(), `anchormd-${name}-${Date.now()}.md`);
+
+      // Provide a template
+      const template = serializePlan(
+        { name, description: 'Description of this plan', status: 'planned' },
+        `# ${name}\n\nDescribe the plan here.\n`
+      );
+      writeFileSync(tmpFile, template, 'utf-8');
+
+      try {
+        execSync(`${editor} "${tmpFile}"`, { stdio: 'inherit' });
+        content = readFileSync(tmpFile, 'utf-8');
+      } catch {
+        console.error(color.red('Error: Editor exited with an error'));
+        process.exit(1);
+      }
+    }
+
+    // Validate or wrap content with frontmatter
+    try {
+      parseFrontmatter(content);
+    } catch {
+      // Content doesn't have valid frontmatter, wrap it
+      content = serializePlan(
+        { name, description: `Plan: ${name}`, status: 'planned' },
+        content
+      );
+    }
+
+    // Write the plan
+    writePlan(plansDir, name, content);
+    console.log(color.green(`Plan "${name}" written.`));
+
+    // Rebuild index
+    const graph = rebuildAndWriteIndex(projectRoot);
+    const nodeCount = Object.keys(graph.nodes).length;
+    console.log(color.dim(`Index rebuilt (${nodeCount} plans).`));
+
+    // Reindex QMD if enabled
+    if (config.qmd) {
+      const store = await getQmdStore(anchorDir, config);
+      await reindexQmd(store);
+    }
+  });
+
+// ─── ls ──────────────────────────────────────────────────────────────────────
+
+program
+  .command('ls')
+  .description('List all plans')
+  .option('--status <status>', 'Filter by status (planned, in-progress, built, deprecated)')
+  .option('--json', 'Output as JSON')
+  .action((options) => {
+    const { projectRoot } = ensureProjectInitialized();
+    const plansDir = getPlansDir(projectRoot);
+
+    let plans = listPlans(plansDir);
+
+    // Filter by status
+    if (options.status) {
+      const status = options.status as PlanStatus;
+      if (!VALID_STATUSES.includes(status)) {
+        console.error(color.red(`Invalid status "${status}". Must be one of: ${VALID_STATUSES.join(', ')}`));
+        process.exit(1);
+      }
+      plans = plans.filter(p => p.frontmatter.status === status);
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(plans, null, 2));
+    } else {
+      console.log(formatPlanTable(plans));
+    }
+  });
+
+// ─── read ────────────────────────────────────────────────────────────────────
+
+program
+  .command('read <name>')
+  .description('Read a plan (supports name#section deep links)')
+  .action((nameArg: string) => {
+    const { projectRoot } = ensureProjectInitialized();
+    const plansDir = getPlansDir(projectRoot);
+
+    // Parse name#section
+    const hashIndex = nameArg.indexOf('#');
+    let planName: string;
+    let section: string | null = null;
+
+    if (hashIndex !== -1) {
+      planName = nameArg.substring(0, hashIndex);
+      section = nameArg.substring(hashIndex + 1);
+    } else {
+      planName = nameArg;
+    }
+
+    const plan = readPlan(plansDir, planName);
+
+    if (section) {
+      // Extract the specified section
+      const sectionContent = extractSection(plan.body, section);
+      if (sectionContent === null) {
+        console.error(color.red(`Section "${section}" not found in plan "${planName}"`));
+        process.exit(1);
+      }
+      console.log(sectionContent);
+    } else {
+      // Print full plan content
+      const fullContent = serializePlan(plan.frontmatter, plan.body);
+      console.log(fullContent);
+    }
+  });
+
+// ─── find ────────────────────────────────────────────────────────────────────
+
+program
+  .command('find <query>')
+  .description('Search plans using QMD')
+  .option('--semantic', 'Use semantic (vector) search')
+  .option('--hybrid', 'Use hybrid search (lexical + semantic)')
+  .option('--limit <n>', 'Maximum number of results', '10')
+  .option('--json', 'Output as JSON')
+  .action(async (query: string, options) => {
+    const { projectRoot, config } = ensureProjectInitialized();
+    const anchorDir = getAnchorDir(projectRoot);
+
+    let mode: 'lexical' | 'semantic' | 'hybrid' = 'lexical';
+    if (options.semantic) mode = 'semantic';
+    if (options.hybrid) mode = 'hybrid';
+
+    const limit = parseInt(options.limit, 10) || 10;
+
+    const store = await getQmdStore(anchorDir, config);
+
+    try {
+      const results = await searchQmd(store, query, { mode, limit });
+
+      if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+      } else {
+        console.log(formatSearchResults(results));
+      }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(color.red(message));
+      process.exit(1);
+    }
+  });
+
+// ─── reindex ─────────────────────────────────────────────────────────────────
+
+program
+  .command('reindex')
+  .description('Rebuild the index graph and QMD search database')
+  .action(async () => {
+    const { projectRoot, config } = ensureProjectInitialized();
+    const anchorDir = getAnchorDir(projectRoot);
+
+    // Rebuild index graph
+    const graph = rebuildAndWriteIndex(projectRoot);
+    const nodeCount = Object.keys(graph.nodes).length;
+    const linkCount = Object.values(graph.nodes).reduce((sum, n) => sum + n.links.length, 0);
+    const weakEdgeCount = Object.values(graph.nodes).reduce((sum, n) => sum + n.weakEdges.length, 0);
+
+    console.log(color.green('Index rebuilt.'));
+    console.log(`  Plans: ${color.cyan(String(nodeCount))}`);
+    console.log(`  Links: ${color.cyan(String(linkCount))}`);
+    console.log(`  Weak edges: ${color.cyan(String(weakEdgeCount))}`);
+
+    // Reindex QMD if enabled
+    if (config.qmd) {
+      const store = await getQmdStore(anchorDir, config);
+      await reindexQmd(store);
+      console.log(color.green('QMD search index updated.'));
+    } else {
+      console.log(color.dim('QMD search: disabled'));
+    }
+  });
+
+// ─── status ──────────────────────────────────────────────────────────────────
+
+program
+  .command('status')
+  .description('Show project status and statistics')
+  .action(() => {
+    const { projectRoot, config } = ensureProjectInitialized();
+    const anchorDir = getAnchorDir(projectRoot);
+
+    const graph = readIndex(anchorDir);
+
+    let planCount = 0;
+    let linkCount = 0;
+    let weakEdgeCount = 0;
+
+    if (graph) {
+      const nodes = Object.values(graph.nodes);
+      planCount = nodes.length;
+      linkCount = nodes.reduce((sum, n) => sum + n.links.length, 0);
+      weakEdgeCount = nodes.reduce((sum, n) => sum + n.weakEdges.length, 0);
+    }
+
+    console.log(formatStatus({
+      planCount,
+      linkCount,
+      weakEdgeCount,
+      qmdEnabled: config.qmd,
+    }));
+  });
+
+// ─── Section extraction helper ───────────────────────────────────────────────
+
+/**
+ * Extract a section from markdown content by heading slug.
+ * Matches heading text case-insensitively, slugified (spaces -> hyphens, lowercase).
+ * Returns content from the matched heading to the next same-level or higher heading.
+ */
+function extractSection(body: string, sectionSlug: string): string | null {
+  const lines = body.split('\n');
+  const targetSlug = sectionSlug.toLowerCase();
+
+  let capturing = false;
+  let captureLevel = 0;
+  const captured: string[] = [];
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = headingMatch[2];
+      const slug = text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+
+      if (capturing) {
+        // Stop if we hit a same-level or higher-level heading
+        if (level <= captureLevel) {
+          break;
+        }
+      }
+
+      if (slug === targetSlug) {
+        capturing = true;
+        captureLevel = level;
+      }
+    }
+
+    if (capturing) {
+      captured.push(line);
+    }
+  }
+
+  if (captured.length === 0) {
+    return null;
+  }
+
+  return captured.join('\n').trimEnd();
+}
+
+// ─── Parse and run ───────────────────────────────────────────────────────────
+
+program.parse(process.argv);

package/src/config.ts

@@ -0,0 +1,91 @@
+/**
+ * Project configuration and root detection
+ *
+ * Manages .anchor/config.json and project root discovery
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import type { AnchorConfig } from './types.js';
+
+const DEFAULT_CONFIG: AnchorConfig = { qmd: false };
+
+/**
+ * Walk up the directory tree looking for .anchor/ directory.
+ * Returns the directory containing .anchor/, or null if not found.
+ */
+export function findProjectRoot(startDir?: string): string | null {
+  let dir = startDir ?? process.cwd();
+
+  while (true) {
+    const anchorPath = path.join(dir, '.anchor');
+    if (existsSync(anchorPath)) {
+      return dir;
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      // Hit filesystem root
+      return null;
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Get the .anchor directory path for a project root
+ */
+export function getAnchorDir(projectRoot: string): string {
+  return path.join(projectRoot, '.anchor');
+}
+
+/**
+ * Get the plans directory path for a project root
+ */
+export function getPlansDir(projectRoot: string): string {
+  return path.join(projectRoot, '.anchor', 'plans');
+}
+
+/**
+ * Load configuration from .anchor/config.json.
+ * Returns defaults if file is missing or malformed.
+ */
+export function loadConfig(projectRoot: string): AnchorConfig {
+  const configPath = path.join(getAnchorDir(projectRoot), 'config.json');
+
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return {
+      qmd: typeof parsed.qmd === 'boolean' ? parsed.qmd : DEFAULT_CONFIG.qmd,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+/**
+ * Save configuration to .anchor/config.json
+ */
+export function saveConfig(projectRoot: string, config: AnchorConfig): void {
+  const anchorDir = getAnchorDir(projectRoot);
+  mkdirSync(anchorDir, { recursive: true });
+  const configPath = path.join(anchorDir, 'config.json');
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Ensure the project has been initialized with anchormd.
+ * Throws with a user-friendly message if .anchor/ is not found.
+ */
+export function ensureProjectInitialized(): { projectRoot: string; config: AnchorConfig } {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    throw new Error(
+      'No AnchorMD project found. Run `anchormd init` to initialize one.'
+    );
+  }
+
+  const config = loadConfig(projectRoot);
+  return { projectRoot, config };
+}