javi-forge 0.1.0 → 1.1.0

package/.releaserc

@@ -35,8 +35,9 @@
     ["@semantic-release/exec", {
       "prepareCmd": "echo ${nextRelease.version} > .framework-version"
     }],
+    "@semantic-release/npm",
     ["@semantic-release/git", {
-      "assets": ["CHANGELOG.md", ".framework-version"],
+      "assets": ["CHANGELOG.md", "package.json", ".framework-version"],
       "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
     }],
     "@semantic-release/github"

package/README.md

@@ -1,45 +1,157 @@
 # javi-forge
 
-Project scaffolding and AI-ready CI bootstrap tool.
+> Project scaffolding — AI-ready CI bootstrap with templates for Go, Java, Node, Python, Rust
 
-**javi-forge** generates production-ready project structures with CI/CD pipelines, AI agent configurations, and developer tooling — all from a single command.
+[![npm version](https://img.shields.io/npm/v/javi-forge.svg)](https://www.npmjs.com/package/javi-forge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-## Directory Structure
+## Quick Start
 
+```bash
+npx javi-forge init
 ```
-javi-forge/
-├── README.md              # This file
-├── .gitignore             # Standard ignores
-├── package.json           # Package metadata and scripts
-├── templates/             # CI/CD pipeline templates
-│   ├── github/            # GitHub Actions workflows
-│   ├── gitlab/            # GitLab CI pipelines
-│   ├── woodpecker/        # Woodpecker CI pipelines
-│   ├── common/            # Shared config (dependabot fragments)
-│   └── global/            # AI tool configs (Claude, Copilot, Gemini, etc.)
-├── workflows/             # Reusable GitHub Actions workflows
-├── modules/               # Optional integration modules
-│   ├── engram/            # Persistent memory via Engram MCP
-│   ├── obsidian-brain/    # Obsidian-based project memory
-│   ├── ghagga/            # Multi-agent code review system
-│   └── memory-simple/     # Minimal file-based project memory
-├── ai-config/             # AI agent and skill library
-│   ├── agents/            # Agent definitions (by domain)
-│   ├── skills/            # Skill definitions (by domain)
-│   ├── commands/          # Slash-command definitions
-│   ├── hooks/             # Pre/post tool-use hooks
-│   └── prompts/           # System prompts and modes
-├── schemas/               # JSON schemas for validation
-├── tasks/                 # Task templates
-└── src/                   # CLI source code
+
+An interactive TUI guides you through project setup: pick a stack, CI provider, memory module, and get a production-ready project structure in seconds.
+
+## What It Creates
+
+`javi-forge init` bootstraps a complete project with 10 sequential steps:
+
+```mermaid
+flowchart LR
+    A["javi-forge init"] --> B["git init"]
+    B --> C["CI workflow"]
+    C --> D[".gitignore"]
+    D --> E["dependabot.yml"]
+    E --> F["Memory module"]
+    F --> G["javi-ai sync"]
+    G --> H["openspec/ (SDD)"]
+    H --> I["GHAGGA review"]
+    I --> J["Manifest"]
 ```
 
-## Quick Start
+### Step-by-Step
+
+| Step | What it does |
+|------|-------------|
+| 1 | Initialize git repository |
+| 2 | Configure git hooks path (`ci-local/hooks`) |
+| 3 | Copy CI workflow for your stack and provider |
+| 4 | Generate `.gitignore` from template |
+| 5 | Generate `dependabot.yml` (GitHub only) |
+| 6 | Install memory module (engram, obsidian-brain, or memory-simple) |
+| 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` |
+
+## Templates
+
+| Stack | CI Templates | Dependabot |
+|-------|-------------|------------|
+| **node** | GitHub Actions, GitLab CI, Woodpecker | npm |
+| **python** | GitHub Actions, GitLab CI, Woodpecker | pip |
+| **go** | GitHub Actions, GitLab CI, Woodpecker | gomod |
+| **java-gradle** | GitHub Actions, GitLab CI, Woodpecker | gradle |
+| **java-maven** | GitHub Actions, GitLab CI, Woodpecker | maven |
+| **rust** | GitHub Actions, GitLab CI, Woodpecker | cargo |
+| **elixir** | GitHub Actions, GitLab CI, Woodpecker | — |
+
+## CI Providers
+
+| Provider | Workflow location | Dependabot |
+|----------|------------------|------------|
+| **GitHub Actions** | `.github/workflows/ci.yml` | `.github/dependabot.yml` |
+| **GitLab CI** | `.gitlab-ci.yml` | — |
+| **Woodpecker** | `.woodpecker.yml` | — |
+
+## Memory Modules
+
+| Module | Description |
+|--------|-------------|
+| **engram** | Persistent AI memory via MCP server. Best for cross-session context |
+| **obsidian-brain** | Obsidian-based project memory with Kanban, Dataview, and session tracking |
+| **memory-simple** | Minimal file-based project memory |
+| **none** | Skip memory module |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Bootstrap a new project (default) |
+| `analyze` | Run repoforge skills analysis on current project |
+| `doctor` | Show comprehensive health report |
 
 ```bash
-npx javi-forge init my-project --stack node --ci github
+npx javi-forge init
+npx javi-forge init --stack node --ci github
+npx javi-forge analyze
+npx javi-forge doctor
 ```
 
+### CLI Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--dry-run` | boolean | `false` | Preview without writing files |
+| `--stack` | string | — | Project stack |
+| `--ci` | string | — | CI provider |
+| `--memory` | string | — | Memory module |
+| `--project-name` | string | — | Project name (skips name prompt) |
+| `--ghagga` | boolean | `false` | Enable GHAGGA review system |
+| `--batch` | boolean | `false` | Non-interactive mode |
+
+## AI Config
+
+`javi-forge` ships with a comprehensive `.ai-config/` library:
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| **Agents** | 8 groups | Domain-specific agent definitions |
+| **Skills** | 84 skills | Organized by domain (backend, frontend, infra, etc.) |
+| **Commands** | 20 | Slash-command definitions for Claude |
+| **Hooks** | 11 | Pre/post tool-use automation hooks |
+
+The AI config is synced into your project via `javi-ai sync` during init.
+
+## RepoForge Integration
+
+The `analyze` command wraps [repoforge](https://github.com/Gentleman-Programming/repoforge) to run skills analysis on your project:
+
+```bash
+npx javi-forge analyze
+```
+
+This requires `repoforge` to be installed (`pip install repoforge`). It analyzes your codebase and generates skill recommendations.
+
+## Doctor
+
+The `doctor` command runs comprehensive health checks:
+
+```bash
+npx javi-forge doctor
+```
+
+### What it checks
+
+- **System Tools** — git, docker, semgrep, node, pnpm
+- **Framework Structure** — templates/, modules/, ai-config/, workflows/, schemas/, ci-local/
+- **Stack Detection** — Detects project type from files (package.json, go.mod, Cargo.toml, etc.)
+- **Project Manifest** — Reads `.javi-forge/manifest.json`
+- **Installed Modules** — engram, obsidian-brain, memory-simple, ghagga
+
+## Requirements
+
+- **Node.js** >= 18
+
+## Ecosystem
+
+| Package | Description |
+|---------|-------------|
+| [javi-dots](https://github.com/JNZader/javi-dots) | Workstation setup (top-level orchestrator) |
+| [javi-ai](https://github.com/JNZader/javi-ai) | AI development layer (called by forge during sync) |
+| **javi-forge** | Project scaffolding (this package) |
+
 ## License
 
-MIT
+[MIT](LICENSE)

package/ai-config/commands/workflows/diagnose.md

@@ -0,0 +1,70 @@
+---
+name: diagnose
+description: Chained diagnosis workflow — investigate issue, verify with devil's advocate, then solve. Uses ACH (Analysis of Competing Hypotheses).
+category: workflows
+chain:
+  - investigate
+  - verify
+  - solve
+suggests_next:
+  - /workflows:compound
+  - /workflows:review
+---
+
+# /workflows:diagnose
+
+Structured diagnosis workflow for complex bugs and issues.
+
+## Usage
+
+```
+/workflows:diagnose <issue-description>
+```
+
+## Chain Steps
+
+### Step 1: Investigate
+Gather evidence and generate hypotheses using the debug-mode skill.
+
+1. Reproduce the issue (or understand the reproduction steps)
+2. Gather context: error messages, stack traces, recent changes, logs
+3. Generate 3-5 competing hypotheses ranked by likelihood
+4. Map evidence to hypotheses (which evidence supports/contradicts each)
+
+Output: ACH matrix
+
+```
+## ACH Matrix: <issue>
+| Evidence | H1 (70%) | H2 (20%) | H3 (10%) |
+|----------|----------|----------|----------|
+| Error at line 42 | Consistent | Inconsistent | Neutral |
+| Works in staging | Inconsistent | Consistent | Consistent |
+```
+
+**After completion, suggest**: "Investigation complete. Run step 2 for devil's advocate verification, or jump to step 3 if confident."
+
+### Step 2: Verify (Devil's Advocate)
+Challenge the leading hypothesis:
+
+1. **Assume H1 is wrong** — what evidence would you expect to see?
+2. **Check for that evidence** — does it exist?
+3. **Try to reproduce with H1 fixed** — does the fix actually work?
+4. If H1 survives the challenge, proceed to fix. Otherwise, promote H2.
+
+**After completion, suggest**: "Verification complete. H[N] confirmed. Run step 3 to implement the fix."
+
+### Step 3: Solve
+Implement the fix based on the verified hypothesis:
+
+1. Write the fix
+2. Verify the original reproduction steps pass
+3. Run the full test suite
+4. Document what was wrong and why (for Engram)
+
+**After completion, suggest**: "Fix applied. Next: `/workflows:compound` to capture learnings, or `/workflows:review` for code review."
+
+## Rules
+
+1. Never skip step 2 for Medium+ complexity issues
+2. Always document the root cause in Engram
+3. If 3 rounds of investigation don't converge, escalate to user

package/ai-config/commands/workflows/discover.md

@@ -0,0 +1,86 @@
+---
+name: discover
+description: Chained discovery workflow — brainstorm ideas, identify assumptions, prioritize experiments, then execute. Progressive suggestions after each step.
+category: workflows
+chain:
+  - brainstorm
+  - identify-assumptions
+  - prioritize
+  - experiment
+suggests_next:
+  - /workflows:plan
+  - /workflows:work
+---
+
+# /workflows:discover
+
+End-to-end discovery workflow that chains 4 steps with progressive suggestions.
+
+## Usage
+
+```
+/workflows:discover <topic>
+```
+
+## Chain Steps
+
+### Step 1: Brainstorm
+Generate 5-10 ideas related to the topic. No filtering, quantity over quality.
+
+Output format:
+```
+## Ideas for: <topic>
+1. [idea] — [one-line rationale]
+2. [idea] — [one-line rationale]
+...
+```
+
+**After completion, suggest**: "Ideas generated. Run step 2 to identify assumptions, or pick specific ideas to explore."
+
+### Step 2: Identify Assumptions
+For the top 3-5 ideas, list the key assumptions that must be true for each to work.
+
+Output format:
+```
+## Assumptions
+### Idea 1: [name]
+- [assumption] — risk: high/medium/low
+- [assumption] — risk: high/medium/low
+```
+
+**After completion, suggest**: "Assumptions mapped. Run step 3 to prioritize by risk, or go back to brainstorm more."
+
+### Step 3: Prioritize
+Rank ideas by: (1) impact, (2) effort, (3) assumption risk. Create a 2x2 matrix.
+
+Output format:
+```
+## Priority Matrix
+| Idea | Impact | Effort | Risk | Priority |
+|------|--------|--------|------|----------|
+```
+
+**After completion, suggest**: "Priority matrix ready. Run step 4 to design experiments for the top picks."
+
+### Step 4: Experiment Design
+For the top 2-3 ideas, design a minimal experiment to validate the riskiest assumption.
+
+Output format:
+```
+## Experiments
+### Experiment 1: [name]
+- Validates: [assumption]
+- Method: [how to test]
+- Success criteria: [what proves it works]
+- Effort: [time estimate]
+```
+
+**After completion, suggest**: "Experiments designed. Next steps: `/workflows:plan` to plan implementation, or `/workflows:work` to start building."
+
+## Chaining Rules
+
+1. Each step can be run independently or as part of the chain
+2. Output of each step is input context for the next
+3. Progressive suggestions appear after every step completion
+4. User can skip steps or go back at any point
+5. The full chain takes ~15 minutes of agent time

package/ci-local/ci-local.sh

@@ -74,6 +74,12 @@ setup_ci_commands() {
     esac
 }
 
+# Check if GHAGGA is available on the host
+GHAGGA_AVAILABLE=false
+if command -v ghagga >/dev/null 2>&1; then
+    GHAGGA_AVAILABLE=true
+fi
+
 # =============================================================================
 # DOCKER
 # =============================================================================
@@ -270,6 +276,7 @@ case "$MODE" in
         [[ -n "$LINT_CMD" ]] && total=$((total + 1))
         [[ -n "$COMPILE_CMD" ]] && total=$((total + 1))
         [[ -n "$TEST_CMD" ]] && total=$((total + 1))
+        if $GHAGGA_AVAILABLE; then total=$((total + 1)); fi
 
         if [[ -n "$LINT_CMD" ]]; then
             echo -e "\n${YELLOW}Step $step/$total: Lint${NC}"
@@ -289,6 +296,17 @@ case "$MODE" in
             echo -e "\n${YELLOW}Step $step/$total: Test${NC}"
             echo -e "  ${CYAN}$TEST_CMD${NC}"
             run_in_ci "cd /home/runner/work && $TEST_CMD"
+            step=$((step + 1))
+        fi
+
+        if $GHAGGA_AVAILABLE; then
+            echo -e "\n${YELLOW}Step $step/$total: GHAGGA Review${NC}"
+            echo -e "  ${CYAN}ghagga review --plain --exit-on-issues${NC}"
+            if ! ghagga review --plain --exit-on-issues; then
+                echo -e "${RED}GHAGGA review found issues!${NC}"
+                exit 1
+            fi
+            step=$((step + 1))
         fi
         ;;
 esac

package/ci-local/docker/node.Dockerfile

@@ -0,0 +1,7 @@
+FROM node:22-slim
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN npm install -g pnpm
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

package/dist/commands/doctor.js

@@ -3,7 +3,8 @@ import path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { detectStack } from '../lib/common.js';
-import { FORGE_ROOT, TEMPLATES_DIR, MODULES_DIR, AI_CONFIG_DIR } from '../constants.js';
+import { listInstalledPlugins } from '../lib/plugin.js';
+import { FORGE_ROOT, TEMPLATES_DIR, MODULES_DIR, AI_CONFIG_DIR, PLUGINS_DIR } from '../constants.js';
 const execFileAsync = promisify(execFile);
 /** Resolve a binary name to its full path, returns null if not found */
 async function which(bin) {
@@ -153,6 +154,28 @@ export async function runDoctor(projectDir) {
         }
     }
     sections.push({ title: 'Installed Modules', checks: moduleChecks });
+    // ── 6. Plugins ─────────────────────────────────────────────────────────────
+    const pluginChecks = [];
+    const pluginsDirExists = await fs.pathExists(PLUGINS_DIR);
+    if (pluginsDirExists) {
+        const plugins = await listInstalledPlugins();
+        if (plugins.length > 0) {
+            for (const plugin of plugins) {
+                pluginChecks.push({
+                    label: plugin.name,
+                    status: 'ok',
+                    detail: `v${plugin.version} from ${plugin.source}`,
+                });
+            }
+        }
+        else {
+            pluginChecks.push({ label: 'Plugins', status: 'skip', detail: 'none installed' });
+        }
+    }
+    else {
+        pluginChecks.push({ label: 'Plugins directory', status: 'skip', detail: 'not created yet' });
+    }
+    sections.push({ title: 'Plugins', checks: pluginChecks });
     return { sections };
 }
 //# sourceMappingURL=doctor.js.map

package/dist/commands/init.js

@@ -250,7 +250,54 @@ export async function initProject(options, onStep) {
     catch (e) {
         report(onStep, stepGhagga, 'Install GHAGGA review system', 'error', String(e));
     }
-    // ── Step 10: Write manifest ───────────────────────────────────────────────
+    // ── Step 10: Mock-first mode ───────────────────────────────────────────────
+    const stepMock = 'mock';
+    if (options.mock) {
+        report(onStep, stepMock, 'Configure mock-first mode', 'running');
+        try {
+            if (!dryRun) {
+                // Create .env.example with mock values
+                const envExample = `# Mock environment — no real API keys required
+# Copy to .env to use: cp .env.example .env
+
+# Database
+DATABASE_URL=postgresql://mock:mock@localhost:5432/mock_db
+
+# Auth
+JWT_SECRET=mock-jwt-secret-for-local-development
+SESSION_SECRET=mock-session-secret
+
+# External APIs (mock mode — no real calls)
+MOCK_MODE=true
+API_KEY=mock-api-key-not-real
+STRIPE_KEY=sk_test_mock_not_real
+SENDGRID_KEY=SG.mock_not_real
+
+# Feature flags
+ENABLE_ANALYTICS=false
+ENABLE_EMAILS=false
+ENABLE_WEBHOOKS=false
+`;
+                const envExamplePath = path.join(projectDir, '.env.example');
+                if (!await fs.pathExists(envExamplePath)) {
+                    await fs.writeFile(envExamplePath, envExample, 'utf-8');
+                }
+                // Create .env from example
+                const envPath = path.join(projectDir, '.env');
+                if (!await fs.pathExists(envPath)) {
+                    await fs.writeFile(envPath, envExample, 'utf-8');
+                }
+            }
+            report(onStep, stepMock, 'Configure mock-first mode', 'done', '.env.example + .env with mock values');
+        }
+        catch (e) {
+            report(onStep, stepMock, 'Configure mock-first mode', 'error', String(e));
+        }
+    }
+    else {
+        report(onStep, stepMock, 'Configure mock-first mode', 'skipped', 'not selected');
+    }
+    // ── Step 11: Write manifest ───────────────────────────────────────────────
     const stepManifest = 'manifest';
     report(onStep, stepManifest, 'Write forge manifest', 'running');
     try {

package/dist/commands/llmstxt.d.ts

@@ -0,0 +1,9 @@
+import type { InitStep } from '../types/index.js';
+type StepCallback = (step: InitStep) => void;
+/**
+ * Generate an llms.txt file — compact AI-friendly project notation.
+ * Reduces token usage by ~75% compared to full README + docs.
+ */
+export declare function generateLlmsTxt(projectDir: string, dryRun: boolean, onStep: StepCallback): Promise<void>;
+export {};
+//# sourceMappingURL=llmstxt.d.ts.map

package/dist/commands/llmstxt.js

@@ -0,0 +1,93 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { glob } from 'glob';
+import { detectStack } from '../lib/common.js';
+function report(onStep, id, label, status, detail) {
+    onStep({ id, label, status, detail });
+}
+/**
+ * Generate an llms.txt file — compact AI-friendly project notation.
+ * Reduces token usage by ~75% compared to full README + docs.
+ */
+export async function generateLlmsTxt(projectDir, dryRun, onStep) {
+    report(onStep, 'scan', 'Scan project structure', 'running');
+    const detection = await detectStack(projectDir);
+    const stackLabel = detection?.stackType ?? 'unknown';
+    // Gather project info
+    const name = path.basename(projectDir);
+    let description = '';
+    let version = '';
+    let entryPoints = [];
+    let dependencies = [];
+    // Try package.json (Node)
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (await fs.pathExists(pkgPath)) {
+        try {
+            const pkg = await fs.readJson(pkgPath);
+            description = pkg.description ?? '';
+            version = pkg.version ?? '';
+            entryPoints = pkg.main ? [pkg.main] : [];
+            dependencies = Object.keys(pkg.dependencies ?? {}).slice(0, 15);
+        }
+        catch { /* ignore */ }
+    }
+    // Scan source files
+    const sourceFiles = await glob('src/**/*.{ts,tsx,js,jsx,py,go,rs}', {
+        cwd: projectDir,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/.git/**'],
+    });
+    // Scan test files
+    const testFiles = await glob('**/*.{test,spec}.{ts,tsx,js,jsx,py}', {
+        cwd: projectDir,
+        ignore: ['**/node_modules/**', '**/dist/**'],
+    });
+    report(onStep, 'scan', 'Scan project structure', 'done', `${sourceFiles.length} source, ${testFiles.length} test files`);
+    // Build llms.txt content
+    report(onStep, 'generate', 'Generate llms.txt', 'running');
+    const lines = [
+        `# ${name}`,
+        '',
+        `> ${description || 'No description'}`,
+        '',
+        `- stack: ${stackLabel}${detection?.buildTool ? ` (${detection.buildTool})` : ''}`,
+        `- version: ${version || 'unknown'}`,
+        `- files: ${sourceFiles.length} source, ${testFiles.length} tests`,
+        '',
+    ];
+    // Structure summary (compact)
+    if (sourceFiles.length > 0) {
+        lines.push('## Structure');
+        const dirs = new Map();
+        for (const f of sourceFiles) {
+            const dir = path.dirname(f);
+            dirs.set(dir, (dirs.get(dir) ?? 0) + 1);
+        }
+        for (const [dir, count] of [...dirs.entries()].sort().slice(0, 20)) {
+            lines.push(`- ${dir}/ (${count})`);
+        }
+        lines.push('');
+    }
+    // Dependencies (compact — name only, no versions)
+    if (dependencies.length > 0) {
+        lines.push('## Dependencies');
+        lines.push(dependencies.join(', '));
+        lines.push('');
+    }
+    // Entry points
+    if (entryPoints.length > 0) {
+        lines.push('## Entry');
+        for (const ep of entryPoints) {
+            lines.push(`- ${ep}`);
+        }
+        lines.push('');
+    }
+    const content = lines.join('\n');
+    const tokenEstimate = Math.ceil(content.length / 4);
+    if (!dryRun) {
+        await fs.writeFile(path.join(projectDir, 'llms.txt'), content, 'utf-8');
+    }
+    report(onStep, 'generate', 'Generate llms.txt', 'done', dryRun
+        ? `dry-run: ~${tokenEstimate} tokens (${content.length} chars)`
+        : `written — ~${tokenEstimate} tokens (${content.length} chars)`);
+}
+//# sourceMappingURL=llmstxt.js.map

package/dist/commands/llmstxt.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llmstxt.test.d.ts.map

package/dist/commands/plugin.d.ts

@@ -0,0 +1,24 @@
+import type { InitStep } from '../types/index.js';
+type StepCallback = (step: InitStep) => void;
+/**
+ * Add (install) a plugin from a GitHub source.
+ */
+export declare function runPluginAdd(source: string, dryRun: boolean, onStep: StepCallback): Promise<void>;
+/**
+ * Remove an installed plugin by name.
+ */
+export declare function runPluginRemove(name: string, dryRun: boolean, onStep: StepCallback): Promise<void>;
+/**
+ * List all installed plugins.
+ */
+export declare function runPluginList(onStep: StepCallback): Promise<void>;
+/**
+ * Search the remote plugin registry.
+ */
+export declare function runPluginSearch(query: string | undefined, onStep: StepCallback): Promise<void>;
+/**
+ * Validate a local plugin directory.
+ */
+export declare function runPluginValidate(pluginDir: string, onStep: StepCallback): Promise<void>;
+export {};
+//# sourceMappingURL=plugin.d.ts.map