javi-forge 1.5.0 → 1.6.1

package/README.md

@@ -15,7 +15,7 @@ An interactive TUI guides you through project setup: pick a stack, CI provider,
 
 ## What It Creates
 
-`javi-forge init` bootstraps a complete project with 10 sequential steps:
+`javi-forge init` bootstraps a complete project with 13 sequential steps:
 
 ```mermaid
 flowchart LR
@@ -27,7 +27,10 @@ flowchart LR
     F --> G["javi-ai sync"]
     G --> H["openspec/ (SDD)"]
     H --> I["GHAGGA review"]
-    I --> J["Manifest"]
+    I --> J["Mock mode"]
+    J --> K[".context/"]
+    K --> L["CLAUDE.md"]
+    L --> M["Manifest"]
 ```
 
 ### Step-by-Step
@@ -43,7 +46,10 @@ flowchart LR
 | 7 | Sync AI config via `javi-ai sync --target all` |
 | 8 | Set up SDD with `openspec/` directory |
 | 9 | Install GHAGGA review system (optional) |
-| 10 | Write forge manifest to `.javi-forge/manifest.json` |
+| 10 | Configure mock-first mode (optional) |
+| 11 | Generate `.context/` directory with `INDEX.md` and `summary.md` |
+| 12 | Generate project-aware `CLAUDE.md` (stack, conventions, skills) |
+| 13 | Write forge manifest to `.javi-forge/manifest.json` |
 
 ## Templates
 
@@ -79,14 +85,45 @@ flowchart LR
 | Command | Description |
 |---------|-------------|
 | `init` | Bootstrap a new project (default) |
+| `ci` | Run CI simulation (lint + compile + test + security + ghagga) |
+| `ci init` | Install git hooks in `.git/hooks/` (recommended for existing repos) |
+| `tdd init` | Install TDD-enforcing pre-commit hook (auto-detects stack) |
 | `analyze` | Run repoforge skills analysis on current project |
 | `doctor` | Show comprehensive health report |
+| `plugin add` | Install a plugin from GitHub (`org/repo`) |
+| `plugin remove` | Remove an installed plugin |
+| `plugin list` | List installed plugins |
+| `plugin search` | Search the plugin registry |
+| `plugin validate` | Validate a local plugin directory |
+| `plugin sync` | Auto-detect and wire installed plugins into manifest |
+| `plugin export` | Export plugin to Agent Skills spec (`skills.json`) |
+| `plugin export --codex` | Export plugin to Codex-compatible TOML subagent files |
+| `plugin import` | Import an Agent Skills spec package as a javi-forge plugin |
+| `skills doctor` | Show skills health report (conflict + duplicate detection) |
+| `skills budget` | Show token cost of loaded skills |
+| `skills score` | Score a skill on quality dimensions (0-100) |
+| `skills benchmark` | Benchmark a skill with structural quality checks |
+| `security baseline` | Create security baseline from current audit findings |
+| `security check` | Check for regressions against baseline (exits non-zero if found) |
+| `security update` | Re-snapshot baseline (acknowledge current vulns) |
+| `llms-txt` | Generate AI-friendly `llms.txt` for current project |
 
 ```bash
 npx javi-forge init
 npx javi-forge init --stack node --ci github
+npx javi-forge ci
+npx javi-forge ci init
+npx javi-forge tdd init
 npx javi-forge analyze
 npx javi-forge doctor
+npx javi-forge plugin sync
+npx javi-forge plugin export my-plugin --codex
+npx javi-forge skills doctor --deep
+npx javi-forge skills budget -b 10000
+npx javi-forge skills score react-19
+npx javi-forge security baseline
+npx javi-forge security check
+npx javi-forge llms-txt
 ```
 
 ### CLI Flags
@@ -98,8 +135,20 @@ npx javi-forge doctor
 | `--ci` | string | — | CI provider |
 | `--memory` | string | — | Memory module |
 | `--project-name` | string | — | Project name (skips name prompt) |
+| `--no-docker` | boolean | `false` | Disable Docker in CI hooks |
+| `--no-ci-ghagga` | boolean | `false` | Disable GHAGGA in CI hooks |
+| `--no-security` | boolean | `false` | Skip Semgrep security scan in CI |
 | `--ghagga` | boolean | `false` | Enable GHAGGA review system |
+| `--mock` | boolean | `false` | Enable mock-first mode (no real API keys) |
 | `--batch` | boolean | `false` | Non-interactive mode |
+| `--quick` | boolean | `false` | Lint + compile only (CI mode) |
+| `--shell` | boolean | `false` | Open interactive shell in CI container |
+| `--detect` | boolean | `false` | Show detected stack and exit (CI mode) |
+| `--timeout` | number | `600` | Per-step timeout in seconds (CI mode) |
+| `--deep` | boolean | `false` | Enable deep analysis (skills conflict detection) |
+| `--budget, -b` | number | `8000` | Token budget limit for skills |
+| `--skills-dir` | string | — | Custom skills directory path |
+| `--codex` | boolean | `false` | Export plugin as Codex TOML (plugin export) |
 
 ## AI Config
 
@@ -114,6 +163,145 @@ npx javi-forge doctor
 
 The AI config is synced into your project via `javi-ai sync` during init.
 
+## Context Directory Generation
+
+During `init`, javi-forge generates a `.context/` directory with two files:
+
+| File | Purpose |
+|------|---------|
+| `.context/INDEX.md` | File index with directory structure, entry point, and conventions |
+| `.context/summary.md` | Project summary for AI agents |
+
+The content is stack-aware: it uses the detected stack (node, python, go, etc.) to generate relevant directory trees, entry points, and convention hints. AI tools can read `.context/` for instant project understanding.
+
+## CLAUDE.md Generation
+
+`init` generates a project-level `CLAUDE.md` tailored to your stack. It includes:
+
+- Stack and runtime information
+- Coding conventions and test framework
+- Relevant skills to load (e.g., `react-19`, `typescript`, `tailwind-4`)
+- Installed modules (memory, SDD, GHAGGA)
+- Reference to `.context/` directory if enabled
+
+This gives Claude Code immediate project awareness without manual configuration.
+
+## Plugin System
+
+Manage javi-forge plugins (skills, hooks, agents):
+
+```bash
+npx javi-forge plugin add mapbox/agent-skills   # install from GitHub
+npx javi-forge plugin remove agent-skills        # remove by name
+npx javi-forge plugin list                       # list installed
+npx javi-forge plugin search "react"             # search registry
+npx javi-forge plugin validate ./my-plugin       # validate local plugin
+npx javi-forge plugin sync                       # auto-detect and wire plugins
+```
+
+### Plugin Sync
+
+`plugin sync` scans the project for installed plugins and updates the forge manifest. It detects additions, removals, and unchanged plugins:
+
+```bash
+npx javi-forge plugin sync
+# added: my-plugin | unchanged: core-skills
+```
+
+### Agent Skills Interop
+
+Export javi-forge plugins to the Agent Skills spec or Codex TOML format for cross-tool compatibility:
+
+```bash
+npx javi-forge plugin export my-plugin           # exports skills.json (Agent Skills spec)
+npx javi-forge plugin export my-plugin --codex   # exports .toml subagent files (Codex)
+npx javi-forge plugin import ./agent-skills-pkg  # import Agent Skills package as plugin
+```
+
+## Security Baseline
+
+Track and detect security regressions with baseline snapshots:
+
+```bash
+npx javi-forge security baseline   # create baseline from current audit
+npx javi-forge security check      # check for regressions (non-zero exit if found)
+npx javi-forge security update     # re-snapshot baseline (acknowledge current vulns)
+```
+
+Supports **node** (npm/pnpm/yarn audit), **python** (pip-audit), **go** (govulncheck), and **rust** (cargo audit). The baseline is stored in `.javi-forge/security-baseline.json`.
+
+`security check` compares current findings against the baseline and reports regressions (new vulnerabilities) and resolutions. It exits non-zero when regressions are found, making it suitable for CI pipelines.
+
+## TDD Hook
+
+Install a test-driven development pre-commit hook that enforces tests must pass before any commit:
+
+```bash
+npx javi-forge tdd init
+```
+
+Auto-detects your stack and wires the correct test command (`npm test`, `pytest`, `go test ./...`). To bypass: `git commit --no-verify`.
+
+## Skills Management
+
+### Skills Doctor
+
+Analyze installed skills for health, conflicts, and duplicates:
+
+```bash
+npx javi-forge skills doctor          # basic health + token budget
+npx javi-forge skills doctor --deep   # + conflict detection + duplicate detection
+```
+
+With `--deep`, the doctor scans all SKILL.md critical rules for contradictions (e.g., "use semicolons" vs "no semicolons") and detects overlapping trigger keywords between skills.
+
+### Skills Budget
+
+Show token cost of all loaded skills and check against a budget:
+
+```bash
+npx javi-forge skills budget           # default budget: 8000 tokens
+npx javi-forge skills budget -b 12000  # custom budget
+```
+
+Lists skills sorted by token consumption and suggests which to disable if over budget.
+
+### Skills Score
+
+Score a skill on four quality dimensions (0-100 each):
+
+```bash
+npx javi-forge skills score react-19
+```
+
+| Dimension | Weight | What it measures |
+|-----------|--------|-----------------|
+| Completeness | 30% | Frontmatter, critical rules, content depth |
+| Clarity | 25% | Actionable rules, no vague terms, structured sections |
+| Testability | 25% | Given/When/Then scenarios, code examples, specificity |
+| Token Efficiency | 20% | Rules-per-1000-tokens ratio, total size |
+
+Exits non-zero if overall score is below threshold (default: 50).
+
+### Skills Benchmark
+
+Run structural quality checks against a skill:
+
+```bash
+npx javi-forge skills benchmark react-19
+```
+
+Checks: frontmatter name, triggers, critical rules (>= 3), actionable verbs, code examples, section headings, token budget (<= 3000), no vague terms. Reports pass rate as a percentage.
+
+## LLMs.txt
+
+Generate an AI-friendly `llms.txt` file with compact project notation (~75% fewer tokens than full docs):
+
+```bash
+npx javi-forge llms-txt
+npx javi-forge llms-txt --dry-run
+```
+
 ## RepoForge Integration
 
 The `analyze` command wraps [repoforge](https://github.com/Gentleman-Programming/repoforge) to run skills analysis on your project:

package/ci-local/hooks/pre-push

@@ -8,17 +8,21 @@
 
 set -e
 
-# Verify Docker is running
-if ! docker info &>/dev/null; then
-    echo "PRE-PUSH: Docker is not running."
-    echo "  Start Docker or use: git push --no-verify"
-    exit 1
+if docker info &>/dev/null; then
+    echo "PRE-PUSH: Running full CI simulation..."
+    javi-forge ci || {
+        echo ""
+        echo "CI FAILED — Push aborted. Fix the issues above before pushing."
+        echo "To skip: git push --no-verify"
+        exit 1
+    }
+else
+    echo "PRE-PUSH: ⚠ Docker not running — running quick checks only (lint + typecheck)"
+    echo "  Start Docker for full CI (security scan, Docker tests)"
+    javi-forge ci --quick --no-docker --no-security --no-ci-ghagga || {
+        echo ""
+        echo "Quick checks FAILED — Push aborted. Fix the issues above before pushing."
+        echo "To skip: git push --no-verify"
+        exit 1
+    }
 fi
-
-echo "PRE-PUSH: Running CI simulation..."
-javi-forge ci || {
-    echo ""
-    echo "CI FAILED — Push aborted. Fix the issues above before pushing."
-    echo "To skip: git push --no-verify"
-    exit 1
-}

package/dist/commands/analyze.d.ts

@@ -1,4 +1,4 @@
-import type { InitStep } from '../types/index.js';
+import type { InitStep } from "../types/index.js";
 type StepCallback = (step: InitStep) => void;
 /**
  * Run repoforge skills analysis on a project directory.

package/dist/commands/analyze.js

@@ -1,5 +1,5 @@
-import { execFile } from 'child_process';
-import { promisify } from 'util';
+import { execFile } from "child_process";
+import { promisify } from "util";
 const execFileAsync = promisify(execFile);
 function report(onStep, id, label, status, detail) {
     onStep({ id, label, status, detail });
@@ -7,7 +7,7 @@ function report(onStep, id, label, status, detail) {
 /** Check if a binary is available in PATH */
 async function which(bin) {
     try {
-        await execFileAsync('which', [bin]);
+        await execFileAsync("which", [bin]);
         return true;
     }
     catch {
@@ -19,37 +19,37 @@ async function which(bin) {
  * This is a thin wrapper that delegates to the repoforge CLI.
  */
 export async function runAnalyze(projectDir, dryRun, onStep) {
-    const stepId = 'analyze-repoforge';
-    report(onStep, stepId, 'Run repoforge skills analysis', 'running');
+    const stepId = "analyze-repoforge";
+    report(onStep, stepId, "Run repoforge skills analysis", "running");
     try {
         // Check if repoforge is installed
-        const hasRepoforge = await which('repoforge');
+        const hasRepoforge = await which("repoforge");
         if (!hasRepoforge) {
-            report(onStep, stepId, 'Run repoforge skills analysis', 'error', 'repoforge not found. Install with: pip install repoforge');
+            report(onStep, stepId, "Run repoforge skills analysis", "error", "repoforge not found. Install with: pip install repoforge");
             return;
         }
-        const args = ['skills', '-w', projectDir];
+        const args = ["skills", "-w", projectDir];
         if (dryRun) {
-            args.push('--dry-run');
+            args.push("--dry-run");
         }
-        const { stdout, stderr } = await execFileAsync('repoforge', args, {
+        const { stdout, stderr } = await execFileAsync("repoforge", args, {
             cwd: projectDir,
             timeout: 300_000, // 5 min — analysis can take a while on large repos
         });
         if (stdout) {
-            report(onStep, stepId, 'Run repoforge skills analysis', 'done', stdout.trim().split('\n').pop() ?? 'complete');
+            report(onStep, stepId, "Run repoforge skills analysis", "done", stdout.trim().split("\n").pop() ?? "complete");
         }
         else {
-            report(onStep, stepId, 'Run repoforge skills analysis', 'done', dryRun ? 'dry-run complete' : 'complete');
+            report(onStep, stepId, "Run repoforge skills analysis", "done", dryRun ? "dry-run complete" : "complete");
         }
         if (stderr) {
-            const warnId = 'analyze-warnings';
-            report(onStep, warnId, 'Analysis warnings', 'skipped', stderr.trim().split('\n').pop() ?? '');
+            const warnId = "analyze-warnings";
+            report(onStep, warnId, "Analysis warnings", "skipped", stderr.trim().split("\n").pop() ?? "");
         }
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        report(onStep, stepId, 'Run repoforge skills analysis', 'error', msg);
+        report(onStep, stepId, "Run repoforge skills analysis", "error", msg);
     }
 }
 //# sourceMappingURL=analyze.js.map

package/dist/commands/atlassian-mcp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Atlassian MCP pre-config — generates MCP server configuration
+ * for Jira and Confluence integration in scaffolded projects.
+ *
+ * Produces a config snippet that can be merged into .claude/settings.json
+ * or any AI agent's MCP configuration.
+ */
+export interface AtlassianConfig {
+    confluenceUrl: string;
+    confluenceUsername: string;
+    jiraUrl: string;
+    jiraUsername: string;
+}
+export interface McpSnippet {
+    mcpServers: Record<string, {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    }>;
+}
+/**
+ * Generate Atlassian MCP config snippet with user-provided values.
+ * Token placeholders remain as env vars for security.
+ */
+export declare function generateAtlassianMcpConfig(config: AtlassianConfig): McpSnippet;
+/**
+ * Generate a template snippet with placeholders (no user input needed).
+ */
+export declare function generateTemplateMcpConfig(): McpSnippet;
+/**
+ * Write the Atlassian MCP snippet to a project directory.
+ */
+export declare function writeAtlassianMcpSnippet(projectDir: string, config?: AtlassianConfig): Promise<string>;
+/**
+ * Merge Atlassian MCP config into an existing settings.json or MCP config file.
+ */
+export declare function mergeIntoSettings(settingsPath: string, config: AtlassianConfig): Promise<void>;
+/**
+ * Copy the template snippet from templates/common/atlassian/.
+ */
+export declare function copyTemplateSnippet(projectDir: string): Promise<string | null>;
+//# sourceMappingURL=atlassian-mcp.d.ts.map

package/dist/commands/atlassian-mcp.js

@@ -0,0 +1,98 @@
+/**
+ * Atlassian MCP pre-config — generates MCP server configuration
+ * for Jira and Confluence integration in scaffolded projects.
+ *
+ * Produces a config snippet that can be merged into .claude/settings.json
+ * or any AI agent's MCP configuration.
+ */
+import fs from "fs-extra";
+import path from "path";
+import { fileURLToPath } from "url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, "../../templates");
+/**
+ * Generate Atlassian MCP config snippet with user-provided values.
+ * Token placeholders remain as env vars for security.
+ */
+export function generateAtlassianMcpConfig(config) {
+    return {
+        mcpServers: {
+            atlassian: {
+                command: "uvx",
+                args: ["mcp-atlassian"],
+                env: {
+                    CONFLUENCE_URL: config.confluenceUrl,
+                    CONFLUENCE_USERNAME: config.confluenceUsername,
+                    CONFLUENCE_API_TOKEN: "${CONFLUENCE_API_TOKEN}",
+                    JIRA_URL: config.jiraUrl,
+                    JIRA_USERNAME: config.jiraUsername,
+                    JIRA_API_TOKEN: "${JIRA_API_TOKEN}",
+                },
+            },
+        },
+    };
+}
+/**
+ * Generate a template snippet with placeholders (no user input needed).
+ */
+export function generateTemplateMcpConfig() {
+    return {
+        mcpServers: {
+            atlassian: {
+                command: "uvx",
+                args: ["mcp-atlassian"],
+                env: {
+                    CONFLUENCE_URL: "__CONFLUENCE_URL__",
+                    CONFLUENCE_USERNAME: "__CONFLUENCE_USERNAME__",
+                    CONFLUENCE_API_TOKEN: "__CONFLUENCE_API_TOKEN__",
+                    JIRA_URL: "__JIRA_URL__",
+                    JIRA_USERNAME: "__JIRA_USERNAME__",
+                    JIRA_API_TOKEN: "__JIRA_API_TOKEN__",
+                },
+            },
+        },
+    };
+}
+/**
+ * Write the Atlassian MCP snippet to a project directory.
+ */
+export async function writeAtlassianMcpSnippet(projectDir, config) {
+    const snippet = config
+        ? generateAtlassianMcpConfig(config)
+        : generateTemplateMcpConfig();
+    const destDir = path.join(projectDir, ".atlassian");
+    await fs.ensureDir(destDir);
+    const destFile = path.join(destDir, "mcp-config-snippet.json");
+    await fs.writeJson(destFile, snippet, { spaces: 2 });
+    return destFile;
+}
+/**
+ * Merge Atlassian MCP config into an existing settings.json or MCP config file.
+ */
+export async function mergeIntoSettings(settingsPath, config) {
+    const snippet = generateAtlassianMcpConfig(config);
+    let existing = {};
+    if (await fs.pathExists(settingsPath)) {
+        existing = await fs.readJson(settingsPath);
+    }
+    const existingServers = existing.mcpServers ?? {};
+    existing.mcpServers = {
+        ...existingServers,
+        ...snippet.mcpServers,
+    };
+    await fs.writeJson(settingsPath, existing, { spaces: 2 });
+}
+/**
+ * Copy the template snippet from templates/common/atlassian/.
+ */
+export async function copyTemplateSnippet(projectDir) {
+    const srcFile = path.join(TEMPLATES_DIR, "common", "atlassian", "mcp-atlassian-snippet.json");
+    if (!(await fs.pathExists(srcFile)))
+        return null;
+    const destDir = path.join(projectDir, ".atlassian");
+    await fs.ensureDir(destDir);
+    const destFile = path.join(destDir, "mcp-config-snippet.json");
+    await fs.copy(srcFile, destFile, { overwrite: true });
+    return destFile;
+}
+//# sourceMappingURL=atlassian-mcp.js.map

package/dist/commands/ci.d.ts

@@ -1,5 +1,5 @@
-import type { Stack } from '../types/index.js';
-export type CIMode = 'full' | 'quick' | 'shell' | 'detect';
+import type { Stack } from "../types/index.js";
+export type CIMode = "full" | "quick" | "shell" | "detect";
 export interface CIOptions {
     projectDir?: string;
     mode?: CIMode;
@@ -12,7 +12,7 @@ export interface CIOptions {
     /** Timeout in seconds for each Docker step (default: 600) */
     timeout?: number;
 }
-export type CIStepStatus = 'pending' | 'running' | 'done' | 'error' | 'skipped';
+export type CIStepStatus = "pending" | "running" | "done" | "error" | "skipped";
 export interface CIStep {
     id: string;
     label: string;