@abhishekchauhan2904/agentforge 0.0.0-stage → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <YOUR NAME>
+
+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

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# agentforge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turn **Cursor**, **OpenCode** or **Gemini CLI** into a structured AI engineering team:
+Plan -> Architect -> Develop -> QA -> Security -> Review -> Quality Gate -> Docs -> Git,
+with human approval checkpoints at every step.
+
+It does not build your app. It builds the **AI workflow around your app**, and adds real engineering controls that prompt-only frameworks lack.
+
+## Quick start
+
+```bash
+npm install
+npm link                 # makes `agentforge` available globally
+cd your-project
+agentforge init          # pick tool, workflow, specialists
+```
+
+Non-interactive: `agentforge init --yes --tool cursor --workflow full --agents backend,frontend,database`
+
+## What gets generated
+
+| Tool | Output |
+|------|--------|
+| Cursor | `.cursor/rules/*.mdc` (orchestrator is always-on) |
+| OpenCode | `.opencode/agents/*.md` + `opencode.json` |
+| Gemini CLI | `GEMINI.md` |
+| All | `.ai/` project memory, `.ai/config.json`, `.ai/reports/` |
+
+## Typical flow
+
+```bash
+agentforge init                      # once per project
+agentforge install-hooks             # commits are blocked if the gate fails
+agentforge start "add admin ticket management"
+agentforge next                      # tells you what to say to your AI
+#   ...agent works, writes .ai/reports/implementation_plan.md...
+agentforge approve                   # verifies the report, advances to the next step
+agentforge status
+```
+
+`approve` refuses to advance until the step's report exists, has its required sections and does not carry a negative verdict; the gate step runs the real tests, lint, build, audit and secret scan. The workflow is enforced by code, not only by prompts. `--force` overrides and is recorded.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `init` / `update` / `uninstall` | Install, refresh or remove agent files. `update` and `uninstall` never touch prompts you edited |
+| `start "task"` / `next` / `approve` / `status` | Run a task through the pipeline |
+| `gate [--strict]` | Tests, lint, type-check, build, `npm audit`, secret scan (+ report validation) |
+| `validate [agent]` | Check agent reports against their contracts |
+| `checkpoint [label]` | Snapshot the whole working tree (including new files) without touching your index or branch |
+| `rollback [tag] [--dry-run] [--yes] [--force]` | Restore a checkpoint; lists exactly what changes first |
+| `install-hooks` / `uninstall-hooks` | Git pre-commit hook running the gate |
+| `cloud` / `cloud init aws\|azure` | AWS/Azure usage and IaC/CI security findings (`.ai/cloud.md`); scaffold a secure OIDC deploy workflow |
+| `api` / `db` / `structure` / `audit` | Static API security map, database safety checks, layering and Flutter structure checks (reports in `.ai/*.md`) |
+| `graph [--print]` | Draw the project as Mermaid diagrams (`.ai/graph.md`): services, databases, calls, folder dependencies, cycles |
+| `services` | List detected services (api / frontend / worker) and the databases they need |
+| `docker init` / `docker check` | Scaffold Dockerfile + compose with secure defaults; lint them (secrets block the gate) |
+| `analyze`, `doctor [--prompts]`, `stats` | Refresh context, check setup / lint prompts, gate history |
+
+## AWS and Azure
+
+```bash
+agentforge cloud                 # what you use + what is dangerous (.ai/cloud.md)
+agentforge docker init           # a container image to deploy
+agentforge cloud init aws        # or: azure. GitHub Actions + OIDC, no stored keys
+```
+
+| Area | What is checked |
+|------|-----------------|
+| **Identity** | Hardcoded AWS keys, Azure account keys / SAS / client secrets, long-lived keys in CI (use OIDC), `Action *` on `Resource *`, `Principal *` |
+| **Network** | SSH, RDP, MySQL, Postgres, Mongo, Redis ... open to `0.0.0.0/0` in security groups, CloudFormation and Azure NSGs; SQL firewall open to every IP |
+| **Data** | Public S3 ACLs, public access block off, public or unencrypted databases, backups off, storage without HTTPS or with TLS < 1.2, public blobs |
+| **Secrets** | Passwords in Terraform/Bicep, unmarked Bicep secrets, plaintext secrets in Lambda/serverless env, committed `terraform.tfstate` and secret `*.tfvars` |
+
+`init` enables the gate item **Cloud Security** when it finds AWS/Azure usage (`cloudCheck` in `.ai/config.json`); only errors block. The **AWS** and **Azure** agents write a design report (services, security, cost, rollback) and are told never to run `terraform apply`, `aws ... delete`, `az group delete` or similar without showing the plan and getting approval. The graph shows which cloud services each service talks to.
+
+The scaffolded workflow runs your tests, builds the image, pushes it to ECR/ACR and updates ECS/Container Apps. Follow `infra/aws/README.md` or `infra/azure/README.md` first: you must create the registry, the OIDC role/credential and the runtime yourself.
+
+## API, database and structure checks
+
+```bash
+agentforge audit        # api + db + structure; exit code 1 if any error
+agentforge api          # .ai/api-map.md: every endpoint with Auth / Roles / Validation / Rate limit
+agentforge db           # .ai/db-map.md: models, schema and query-safety findings
+agentforge structure    # .ai/structure.md: layering + Flutter structure
+```
+
+| Area | What is checked |
+|------|-----------------|
+| **Authentication** | Every route: is `authenticate`/`Depends(get_current_user)`/`@jwt_required`/DRF `IsAuthenticated` applied (directly, on the router, or at the mount)? Data-changing route without auth = **error** |
+| **Authorization** | Role/permission middleware on admin routes; routes acting on a record by id without an ownership/role check (possible IDOR) |
+| **Middleware** | Validation, rate limiting on login/reset, helmet, CORS, central error handling folder |
+| **Controllers / routes** | routes -> controllers -> services -> models; upward imports are errors; logic inside route files is flagged |
+| **Database** | Password `select:false`, unique email, enums, timestamps, FK indexes, NoSQL/SQL injection, mass assignment |
+| **Python** | FastAPI, Flask, Django REST routes + SQLAlchemy/Django models; Python Docker scaffold |
+| **Flutter** | One state-management approach, features/data layout, data must not import UI, tokens in secure storage, https only, no hardcoded keys |
+
+`init` turns the gate checks on when it finds a backend or mobile app (`apiCheck`, `dbCheck`, `structureCheck` in `.ai/config.json`); only **errors** block the gate. The **Python** and **Flutter** agents and the updated **Backend** agent are told to run these commands and fix every error.
+
+## Project graph
+
+```bash
+agentforge graph          # writes .ai/graph.md (also done by init / analyze)
+```
+
+`.ai/graph.md` contains Mermaid diagrams that render on GitHub, in VS Code's Markdown preview and at mermaid.live:
+
+- **System view:** services, databases/brokers, `user -> frontend`, and service-to-service calls.
+- **Module view (per service):** `routes -> controllers -> models` style folder dependencies with import counts.
+- **Circular dependencies:** listed and drawn in red. Add `"graphCheck": true` to `.ai/config.json` to make cycles block the quality gate.
+- **Language breakdown** of the repository.
+
+Agents read the graph before planning, and the Architect/Microservices reports must contain their own Mermaid diagram of the *designed* system (checked by `validate` / `approve`).
+
+**Which language is best?** The tool does not pick one for you. The Architect agent defaults to your existing stack and may recommend another only when a concrete requirement forces it, comparing options against fixed criteria (team skills, ecosystem, performance, concurrency, ops cost, hiring, integration).
+
+## Docker and microservices
+
+```bash
+agentforge services          # client (frontend), server (api, needs mongo)
+agentforge docker init       # Dockerfile + .dockerignore per service, docker-compose.yml with mongo/redis/postgres as needed
+agentforge docker check      # lint; runs without a Docker daemon
+```
+
+Scaffolds use pinned images, multi-stage builds, non-root users and healthchecks, and pass `docker check` with zero warnings. Add the **Microservices Architect** only when you really have (or need) several services; the prompt tells it to prefer a modular monolith when a split is not justified. The **Docker Specialist** handles the container; **DevOps** handles CI/CD and cloud.
+
+## Honest limitations
+
+- **Cloud: agentforge never connects to your AWS or Azure account.** It cannot see what is really deployed, what a live security group allows, or what anything costs. It reads files in your repo. Terraform, CloudFormation and Bicep are matched with regular expressions (not a real parser), so modules, variables and generated templates can hide problems. For depth also run `tfsec`/`checkov`, `cfn-lint`, `az bicep build`, and AWS Config / Defender for Cloud.
+- The scaffolded deploy workflows were checked for valid YAML/JSON and for passing agentforge's own checks, but **not run against a real AWS or Azure account**. Treat them as a starting point and test in a non-production account first. Only GitHub Actions, ECS Fargate and Azure Container Apps are templated; Lambda, App Service, AKS, EKS and Functions are checked but not scaffolded.
+
+- **API/DB/structure checks are static heuristics, not a pentest.** They read code; they do not send requests. Parsed: Express (including `router.route()` chains and mounted routers), FastAPI, Flask, Django REST classes. **Not parsed:** NestJS decorators, Fastify/Koa routes, Django `urls.py` wiring, GraphQL. Auth applied through an unusual helper name can show as "NO": verify before fixing. The IDOR check only sees the handler's own function body.
+- "No index" findings come from the schema files, not the live database. Run `explain` on real queries.
+
+- **Graph:** the module view follows relative `import`/`require` in JS/TS only. Path aliases (`@/...`, tsconfig `paths`), Python, Go and other languages are not traced, and service-to-service links are found only when a URL or `<NAME>_URL`-style variable names the other service. Dotted arrows are inferences. Treat the graph as a fast, mostly-right map, not proof.
+
+- `docker check` is static analysis (regex on Dockerfile/compose). It does not build images or replace `hadolint`/`docker scout`. The scaffold assumes a Node service listening on port 3000 with a `/health` route; adjust it for your app.
+- Service detection looks one level down (and under `services/`, `apps/`, `packages/`) for `package.json`; non-Node services are not detected yet.
+
+- Only **OpenCode** has real subagents. In **Cursor** the Orchestrator is an always-on rule and in **Gemini CLI** all roles live in one `GEMINI.md`; the model follows the process voluntarily. That is why `approve`, the gate and the pre-commit hook exist: they enforce the process in code.
+- Report validation checks structure (sections, length, verdict), not whether a report is truthful. Treat QA/security reports as claims; the gate is the proof.
+- The secret scanner is regex-based: expect some false positives and misses. Use `gitleaks` in CI for depth.
+- `rollback` ends with `git reset -q` (unstages everything; file contents are untouched).
+- Gate commands for Node, Python, Go and Flutter are auto-detected. Edit `.ai/config.json` for anything else.
+
+## Develop / test
+
+```bash
+npm test
+```
+
+## Add your own agent
+
+1. Create `templates/agents/<name>.md` (Role / Rules / Output / STOP).
+2. Register it in `src/registry.js` (`AGENTS`, optionally `SPECIALISTS` and `CONTRACTS`).
+
+## Roadmap ideas
+
+- Pre-commit hook that runs `agentforge gate`
+- `agentforge doctor` to lint your agent prompts
+- Python / Go gate presets
+- GitHub Action that runs the gate on PRs

package/bin/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import prompts from "prompts";
+import { AGENTS, SPECIALISTS, WORKFLOWS } from "../src/registry.js";
+import { generate, uninstall } from "../src/generator.js";
+import { analyze, renderContext } from "../src/analyzer.js";
+import { runGate } from "../src/gate.js";
+import { validateReports } from "../src/validate.js";
+import { createCheckpoint, listCheckpoints, planRollback, rollback } from "../src/checkpoint.js";
+import { installHook, removeHook } from "../src/hooks.js";
+import { loadConfig } from "../src/config.js";
+import { startTask, loadState, describe, approve } from "../src/state.js";
+import { doctor, lintPrompts } from "../src/doctor.js";
+import { readStats } from "../src/stats.js";
+import { dockerInit, lintDocker } from "../src/docker.js";
+import { findServices, isMicroservices } from "../src/services.js";
+import { writeGraph } from "../src/graph.js";
+import { CHECKS, runCheck } from "../src/audit.js";
+import { cloudInit } from "../src/cloud.js";
+
+const cwd = process.cwd();
+const [cmd = "help", ...rest] = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (let i = 0; i < rest.length; i++) {
+  if (rest[i].startsWith("--")) {
+    const k = rest[i].slice(2);
+    flags[k] = rest[i + 1] && !rest[i + 1].startsWith("--") ? rest[++i] : true;
+  } else positional.push(rest[i]);
+}
+const c = { g: (s) => `\x1b[32m${s}\x1b[0m`, r: (s) => `\x1b[31m${s}\x1b[0m`, y: (s) => `\x1b[33m${s}\x1b[0m`, b: (s) => `\x1b[1m${s}\x1b[0m`, d: (s) => `\x1b[2m${s}\x1b[0m` };
+
+const HELP = `${c.b("agentforge")} - turn your AI coding tool into a structured engineering team
+
+${c.b("Setup")}
+  init [--yes --tool T --workflow W --agents a,b]   Install agents (cursor | opencode | gemini)
+  update [--force]                                  Re-generate agent files; skips ones you edited
+  uninstall [--all]                                 Remove generated agent files (--all also removes .ai/)
+  analyze                                           Refresh .ai/project-context.md
+  doctor [--prompts]                                Check setup (and lint the prompt templates)
+
+${c.b("Run a task (workflow enforced by code)")}
+  start "task"       Begin a task: archives old reports, takes a checkpoint, builds the pipeline
+  next               Show the current step and what to tell your AI
+  approve [--force]  Verify the step's report (or gate) and advance
+  status             Show progress
+
+${c.b("Code audits (static, no running server needed)")}
+  api                          Every endpoint with auth / roles / validation / rate-limit, plus findings (.ai/api-map.md)
+  db                           Models, indexes, schema and query-safety findings (.ai/db-map.md)
+  structure                    Layering (routes -> controllers -> services -> models), Flutter structure (.ai/structure.md)
+  cloud                        AWS/Azure services used, IaC + CI findings (.ai/cloud.md)
+  cloud init aws|azure         Scaffold a secure GitHub-OIDC deploy workflow + templates (never overwrites)
+  audit                        Run api + db + structure + cloud
+
+${c.b("Docker & services")}
+  graph [--print]             Draw the project: services, databases, calls, module dependencies, cycles (.ai/graph.md)
+  services                     List detected services (api / frontend / worker)
+  docker init [--force]        Scaffold Dockerfile, .dockerignore and docker-compose.yml (never overwrites)
+  docker check                 Lint Dockerfiles and compose files (errors block the gate)
+
+${c.b("Safety")}
+  gate [--strict]              Tests, lint, build, audit, secret scan
+  validate [agent]             Check agent reports against their contracts
+  checkpoint [label]           Snapshot everything, including new files
+  checkpoints                  List checkpoints
+  rollback [tag] [--dry-run] [--yes] [--force]
+  install-hooks | uninstall-hooks   Block commits when the gate fails
+  stats                        Gate history`;
+
+async function init() {
+  let { tool, workflow } = flags;
+  let specialists = typeof flags.agents === "string" ? flags.agents.split(",").filter(Boolean) : [];
+  if (!flags.yes) {
+    const info = analyze(cwd);
+    const guess = [info.frontend.length && "frontend", info.backend.length && "backend", info.database.length && "database"].filter(Boolean);
+    const a = await prompts([
+      { type: "select", name: "tool", message: "Which AI tool do you use?", choices: [
+        { title: "Cursor", value: "cursor" }, { title: "OpenCode", value: "opencode" }, { title: "Gemini CLI", value: "gemini" }] },
+      { type: "select", name: "workflow", message: "Which workflow?", choices: Object.entries(WORKFLOWS).map(([value, w]) => ({ title: w.label, value })) },
+      { type: "multiselect", name: "specialists", message: "Pick specialist agents (space to select)", hint: "detected stack is pre-selected",
+        choices: SPECIALISTS.map((value) => ({ title: AGENTS[value].title, value, selected: guess.includes(value) })) }
+    ], { onCancel: () => process.exit(1) });
+    ({ tool, workflow } = a);
+    specialists = a.specialists;
+  }
+  tool ||= "cursor"; workflow ||= "standard";
+  report(generate({ tool, workflow, specialists }, cwd, { force: !!flags.force }), true);
+}
+
+function report(res, first) {
+  console.log(c.g(first ? "\nWorkflow installed." : "\nUpdated.") + ` ${res.agents.length} agents: ${res.agents.join(", ")}`);
+  if (res.skipped.length) console.log(c.y(`Kept your edited files (use --force to overwrite): ${res.skipped.join(", ")}`));
+  if (first) console.log(`\nNext steps:\n  1. Review ${c.b(".ai/config.json")} (quality-gate commands)\n  2. ${c.b("agentforge install-hooks")} to block bad commits\n  3. ${c.b('agentforge start "your task"')} then ${c.b("agentforge next")}\n`);
+}
+
+function gate() {
+  const { results, passed } = runGate(cwd, { strictReports: !!flags.strict });
+  console.log(c.b("\nQUALITY GATE\n"));
+  for (const r of results) console.log(`  ${r.name.padEnd(20)} ${r.status === "PASS" ? c.g("PASS") : c.r("FAIL")}`);
+  console.log(`\n  STATUS: ${passed ? c.g("READY") : c.r("BLOCKED")}`);
+  if (!passed) for (const r of results.filter((x) => x.detail)) console.log(`\n${c.b(r.name)}\n${r.detail}`);
+  console.log(c.d("\n  Report saved to .ai/reports/quality_gate.md\n"));
+  process.exit(passed ? 0 : 1);
+}
+
+function showStep(state) {
+  const d = describe(state);
+  if (!d) return console.log(c.g("Task complete. All steps approved."));
+  console.log(`${c.b(`Step ${state.index + 1}/${state.pipeline.length}: ${d.step}`)}\n  ${d.instruction}`);
+  if (d.report) console.log(`  Expected report: ${c.b(d.report)}`);
+  console.log(c.d("  When the agent is done and you are happy: agentforge approve"));
+}
+
+try {
+  switch (cmd) {
+    case "init": await init(); break;
+    case "update": { const cfg = loadConfig(cwd); const sp = cfg.agents.filter((a) => SPECIALISTS.includes(a)); report(generate({ tool: cfg.tool, workflow: cfg.workflow, specialists: sp }, cwd, { force: !!flags.force }), false); break; }
+    case "uninstall": { const r = uninstall(cwd, { all: !!flags.all }); console.log(c.g(`Removed ${r.removed.length} files.`) + (r.kept.length ? c.y(` Kept (edited by you): ${r.kept.join(", ")}`) : "")); break; }
+    case "analyze": fs.mkdirSync(path.join(cwd, ".ai"), { recursive: true }); fs.writeFileSync(path.join(cwd, ".ai/project-context.md"), renderContext(analyze(cwd))); writeGraph(cwd); console.log(c.g("Updated .ai/project-context.md and .ai/graph.md")); break;
+    case "doctor": {
+      const checks = doctor(cwd);
+      if (flags.prompts) lintPrompts().forEach((m) => checks.push({ level: "warn", msg: `prompt: ${m}` }));
+      for (const k of checks) console.log(`  ${k.level === "ok" ? c.g("ok  ") : k.level === "warn" ? c.y("warn") : c.r("FAIL")}  ${k.msg}`);
+      process.exit(checks.some((k) => k.level === "fail") ? 1 : 0);
+    }
+    case "start": { if (!positional[0]) throw new Error('Usage: agentforge start "describe the task"'); const s = startTask(cwd, positional.join(" ")); console.log(c.g("Task started.") + (s.checkpoint ? c.d(` Checkpoint: ${s.checkpoint}`) : c.y(" (no git checkpoint: not a git repo)")) + `\nPipeline: ${s.pipeline.join(" -> ")}\n`); showStep(s); break; }
+    case "next": { const s = loadState(cwd); if (!s) throw new Error('No active task. Run `agentforge start "task"`.'); showStep(s); break; }
+    case "status": { const s = loadState(cwd); if (!s) throw new Error("No active task."); console.log(`Task: ${s.task}`); s.pipeline.forEach((p, i) => console.log(`  ${i < s.index ? c.g("done   ") : i === s.index ? c.y("current") : c.d("pending")} ${p}`)); break; }
+    case "approve": {
+      const r = approve(cwd, { force: !!flags.force });
+      if (!r.ok) { console.log(c.r(`Cannot approve "${r.step}":\n  - ${r.problems.join("\n  - ")}`) + "\n" + c.d("Fix the problems, or use --force to override (recorded).")); process.exit(1); }
+      console.log(c.g(`Approved: ${r.step}\n`)); const s = loadState(cwd); showStep(s); break;
+    }
+    case "validate": { const v = validateReports(cwd, loadConfig(cwd).agents, positional[0] || null); console.log(v.ok ? c.g(`All reports valid: ${v.checked.join(", ") || "(none required)"}`) : c.r("Problems:\n  - " + v.problems.join("\n  - "))); process.exit(v.ok ? 0 : 1); }
+    case "cloud":
+      if (positional[0] === "init") {
+        const r = cloudInit(cwd, positional[1], { force: !!flags.force });
+        r.created.forEach((f) => console.log(c.g("created ") + f)); r.skipped.forEach((f) => console.log(c.y("kept    ") + f + " (exists)")); r.notes.forEach((n) => console.log(c.y("note: ") + n));
+        console.log(c.d(`\nImage context: ${r.context}. These are templates with <PLACEHOLDERS>: read infra/${positional[1]}/README.md, create the cloud resources, then set the GitHub variables.`));
+        break;
+      }
+    // falls through to the shared audit runner when it is not `cloud init`
+    case "api": case "db": case "structure": case "audit": {
+      const keys = cmd === "audit" ? Object.keys(CHECKS) : [cmd];
+      let errors = 0;
+      for (const k of keys) {
+        const r = runCheck(cwd, k);
+        const e = r.findings.filter((f) => f.level === "error").length, w = r.findings.filter((f) => f.level === "warn").length;
+        errors += e;
+        console.log(c.b(`\n${CHECKS[k].gate}`) + c.d(`  (.ai/${CHECKS[k].out})`));
+        if (k === "api") console.log(`  ${r.endpoints.length} endpoint(s): ${r.endpoints.filter((x) => x.auth).length} with auth, ${r.endpoints.filter((x) => x.roles).length} with role checks`);
+        if (k === "cloud") console.log(`  providers: ${r.cloud.providers.join(", ") || "none detected"}   services used: ${[...new Set(r.cloud.services.map((x) => `${x.provider}:${x.name}`))].join(", ") || "none"}   IaC files: ${r.cloud.iac.length}`);
+        if (k === "db") console.log(`  ${r.models.length} model(s): ${r.models.map((m) => m.name).join(", ") || "none"}`);
+        for (const f of r.findings.filter((x) => x.level !== "info").slice(0, flags.all ? 1e6 : 25)) console.log(`  ${f.level === "error" ? c.r("error") : c.y("warn ")}  ${f.file}:${f.line}  ${f.msg}`);
+        if (r.findings.filter((x) => x.level !== "info").length > 25 && !flags.all) console.log(c.d("  ... more in the .ai report (or use --all)"));
+        console.log(`  ${e} error(s), ${w} warning(s)`);
+      }
+      process.exit(errors ? 1 : 0);
+    }
+    case "graph": {
+      const g = writeGraph(cwd);
+      console.log(c.g("Wrote .ai/graph.md") + c.d("  (Mermaid: renders on GitHub, VS Code preview, mermaid.live)"));
+      console.log(`  services: ${g.services.length}   connections: ${g.system.edges.length}   infra: ${g.system.infra.join(", ") || "none"}   module views: ${g.modules.length}`);
+      console.log(`  languages: ${g.languages.slice(0, 4).map(([l, n]) => `${l} ${n}`).join(", ") || "none detected"}`);
+      if (g.cycles.length) { console.log(c.y("\n  Circular dependencies:")); g.cycles.forEach((x) => console.log(`    ${x.service}: ${x.groups.join(" <-> ")}`)); } else console.log(c.g("  No circular dependencies."));
+      if (flags.print) console.log("\n" + g.system.mermaid);
+      break;
+    }
+    case "services": { const sv = findServices(cwd); console.log(isMicroservices(sv) ? c.b("Multi-service system") : c.b("Single deployable")); sv.forEach((x) => console.log(`  ${x.dir.padEnd(18)} ${x.kind.padEnd(9)} ${x.needs.length ? "needs " + x.needs.join(", ") : ""}`)); break; }
+    case "docker": {
+      if (positional[0] === "init") { const r = dockerInit(cwd, { force: !!flags.force }); r.created.forEach((f) => console.log(c.g("created ") + f)); r.skipped.forEach((f) => console.log(c.y("kept    ") + f + " (exists)")); console.log(c.d("\nNext: edit ports/env, then `agentforge docker check` and `docker compose up --build`.")); break; }
+      if (positional[0] === "check") {
+        const { files, findings } = lintDocker(cwd);
+        if (!files.length) { console.log("No Dockerfile or compose file found. Run `agentforge docker init`."); break; }
+        findings.forEach((f) => console.log(`  ${f.level === "error" ? c.r("error") : c.y("warn ")}  ${f.file}:${f.line}  ${f.msg}`));
+        const errs = findings.filter((f) => f.level === "error").length;
+        console.log(`\n${files.length} file(s), ${errs} error(s), ${findings.length - errs} warning(s)`);
+        process.exit(errs ? 1 : 0);
+      }
+      throw new Error("Usage: agentforge docker init | agentforge docker check");
+    }
+    case "gate": gate(); break;
+    case "stats": {
+      const s = readStats(cwd); if (!s) { console.log("No gate runs yet."); break; }
+      console.log(`Gate runs: ${s.total}   passed: ${s.passed}   blocked: ${s.blocked}   pass rate: ${s.passRate}%`);
+      const top = Object.entries(s.byCheck).sort((a, b) => b[1] - a[1]); if (top.length) console.log("Most common failures: " + top.map(([k, n]) => `${k} (${n})`).join(", ")); break;
+    }
+    case "checkpoint": { const r = createCheckpoint(cwd, positional[0]); console.log(c.g(`Checkpoint created: ${r.tag}`) + c.d(` (${r.commit})`)); break; }
+    case "checkpoints": console.log(listCheckpoints(cwd).join("\n") || "No checkpoints yet."); break;
+    case "rollback": {
+      const plan = planRollback(cwd, positional[0], { force: !!flags.force });
+      console.log(`Checkpoint: ${c.b(plan.target)}\n  restore: ${plan.toRestore.length} file(s)${plan.toRestore.map((f) => `\n    ~ ${f}`).join("")}\n  delete:  ${plan.toDelete.length} new file(s)${plan.toDelete.map((f) => `\n    - ${f}`).join("")}`);
+      if (flags["dry-run"]) break;
+      if (!flags.yes) { console.log(c.y("\nNothing changed. Re-run with --yes to apply (or --dry-run to only preview).")); process.exit(1); }
+      rollback(cwd, positional[0], { force: !!flags.force }); console.log(c.g("\nRolled back.")); break;
+    }
+    case "install-hooks": console.log(c.g("Installed: ") + installHook(cwd, { force: !!flags.force })); break;
+    case "uninstall-hooks": console.log(removeHook(cwd) ? c.g("Hook removed.") : "No agentforge hook found."); break;
+    case "help": case "--help": case "-h": console.log(HELP); break;
+    default: console.log(HELP); process.exit(1);
+  }
+} catch (e) { console.error(c.r("Error: ") + e.message); process.exit(1); }

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@abhishekchauhan2904/agentforge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.0",
+  "description": "Turn Cursor, OpenCode or Gemini CLI into a structured AI software team with quality gates, rollback and project memory.",
+  "type": "module",
+  "bin": {
+    "agentforge": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "cursor",
+    "opencode",
+    "gemini-cli",
+    "workflow",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "prompts": "^2.4.2"
+  },
+  "author": "Abhishek Chauhan <singh.21abhishek@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AbhishekChauhan2904/agentforge.git"
+  },
+  "homepage": "https://github.com/AbhishekChauhan2904/agentforge#readme",
+  "bugs": {
+    "url": "https://github.com/AbhishekChauhan2904/agentforge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/analyzer.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findServices, isMicroservices } from "./services.js";
+import { detectCloud } from "./cloud.js";
+
+const read = (p) => { try { return fs.readFileSync(p, "utf8"); } catch { return null; } };
+const exists = (cwd, f) => fs.existsSync(path.join(cwd, f));
+
+const DEP_MAP = {
+  frontend: { react: "React", next: "Next.js", vue: "Vue", svelte: "Svelte", "@angular/core": "Angular", tailwindcss: "Tailwind CSS" },
+  backend:  { express: "Express", fastify: "Fastify", "@nestjs/core": "NestJS", koa: "Koa" },
+  database: { mongoose: "MongoDB (Mongoose)", mongodb: "MongoDB", pg: "PostgreSQL", mysql2: "MySQL", prisma: "Prisma", "@prisma/client": "Prisma", sequelize: "Sequelize", redis: "Redis", ioredis: "Redis" },
+  auth:     { jsonwebtoken: "JWT", passport: "Passport", bcrypt: "bcrypt", bcryptjs: "bcrypt", "next-auth": "NextAuth" },
+  testing:  { jest: "Jest", vitest: "Vitest", mocha: "Mocha", supertest: "Supertest", cypress: "Cypress", "@playwright/test": "Playwright" }
+};
+
+export function analyze(cwd) {
+  const info = { name: path.basename(cwd), languages: [], frontend: [], backend: [], database: [], auth: [], testing: [], scripts: {}, deploy: [], tree: [], services: [], microservices: false, cloud: [] };
+  const pkgRaw = read(path.join(cwd, "package.json"));
+  if (pkgRaw) {
+    try {
+      const pkg = JSON.parse(pkgRaw);
+      info.name = pkg.name || info.name;
+      info.languages.push(exists(cwd, "tsconfig.json") ? "TypeScript" : "JavaScript");
+      info.scripts = pkg.scripts || {};
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      for (const [cat, map] of Object.entries(DEP_MAP))
+        for (const [dep, label] of Object.entries(map))
+          if (deps[dep] && !info[cat].includes(label)) info[cat].push(label);
+    } catch { /* invalid package.json: ignore */ }
+  }
+  if (exists(cwd, "requirements.txt") || exists(cwd, "pyproject.toml")) {
+    info.languages.push("Python");
+    info.pyText = ((read(path.join(cwd, "requirements.txt")) || "") + (read(path.join(cwd, "pyproject.toml")) || "")).toLowerCase();
+    for (const [d, l] of [["django", "Django"], ["flask", "Flask"], ["fastapi", "FastAPI"]]) if (info.pyText.includes(d)) info.backend.push(l);
+    for (const [d, l] of [["pytest", "pytest"]]) if (info.pyText.includes(d) || exists(cwd, "tests")) info.testing.push(l);
+  }
+  if (exists(cwd, "pubspec.yaml")) {
+    info.languages.push("Dart"); info.frontend.push("Flutter");
+    const pub = read(path.join(cwd, "pubspec.yaml")) || "";
+    for (const [k, l] of [["flutter_bloc", "BLoC"], ["provider", "Provider"], ["riverpod", "Riverpod"], ["mobx", "MobX"]]) if (pub.includes(k)) info.frontend.push(l);
+  }
+  if (exists(cwd, "go.mod")) { info.languages.push("Go"); info.testing.push("go test"); }
+  if (exists(cwd, "Dockerfile") || exists(cwd, "docker-compose.yml")) info.deploy.push("Docker");
+  if (exists(cwd, ".github/workflows")) info.deploy.push("GitHub Actions");
+  if (exists(cwd, "nginx.conf")) info.deploy.push("Nginx");
+  info.services = findServices(cwd);
+  info.microservices = isMicroservices(info.services);
+  try { info.cloud = detectCloud(cwd).providers.map((p) => ({ aws: "AWS", azure: "Azure" }[p])); } catch { /* ignore */ }
+  try {
+    info.tree = fs.readdirSync(cwd, { withFileTypes: true })
+      .filter((d) => !d.name.startsWith(".") && d.name !== "node_modules")
+      .map((d) => d.name + (d.isDirectory() ? "/" : ""));
+  } catch { /* ignore */ }
+  return info;
+}
+
+// Choose gate commands from the scripts the project actually has.
+export function detectGateCommands(info) {
+  const s = info.scripts;
+  const gate = [];
+  if (s.test && !/no test specified/.test(s.test)) gate.push({ name: "Tests", cmd: "npm test --silent" });
+  if (s.lint) gate.push({ name: "Lint", cmd: "npm run lint --silent" });
+  if (s.typecheck) gate.push({ name: "Type Check", cmd: "npm run typecheck --silent" });
+  else if (info.languages.includes("TypeScript")) gate.push({ name: "Type Check", cmd: "npx tsc --noEmit" });
+  if (s.build) gate.push({ name: "Build", cmd: "npm run build --silent" });
+  if (info.languages.includes("Python")) {
+    if (info.testing.includes("pytest")) gate.push({ name: "Tests", cmd: "python -m pytest -q" });
+    if ((info.pyText || "").includes("ruff")) gate.push({ name: "Lint", cmd: "ruff check ." });
+  }
+  if (info.languages.includes("Go")) { gate.push({ name: "Tests", cmd: "go test ./..." }); gate.push({ name: "Vet", cmd: "go vet ./..." }); }
+  if (info.frontend.includes("Flutter")) { gate.push({ name: "Analyze", cmd: "flutter analyze" }); gate.push({ name: "Tests", cmd: "flutter test" }); }
+  return gate;
+}
+
+export function renderContext(info) {
+  const list = (a) => (a.length ? a.join(", ") : "not detected");
+  return `# Project Context (auto-generated by agentforge)
+
+Every agent MUST read this file before working. Update it when the stack changes.
+
+| Item | Value |
+|------|-------|
+| Name | ${info.name} |
+| Languages | ${list(info.languages)} |
+| Frontend | ${list(info.frontend)} |
+| Backend | ${list(info.backend)} |
+| Database | ${list(info.database)} |
+| Auth | ${list(info.auth)} |
+| Testing | ${list(info.testing)} |
+| Deployment | ${list(info.deploy)} |
+| Cloud | ${list(info.cloud)} |
+
+## Services (${info.microservices ? "multi-service system" : "single deployable"})
+${info.services.length ? info.services.map((x) => `- \`${x.dir}\` (${x.kind})${x.needs.length ? " needs " + x.needs.join(", ") : ""}`).join("\n") : "- none detected"}
+
+## npm scripts
+${Object.keys(info.scripts).length ? Object.entries(info.scripts).map(([k, v]) => `- \`${k}\`: \`${v}\``).join("\n") : "- none"}
+
+## Top-level layout
+${info.tree.length ? info.tree.map((t) => `- ${t}`).join("\n") : "- empty project"}
+`;
+}