Forge AI

Forge AI is the KnackForge installer and runtime wrapper for governed software delivery. It packages Forge SDLC and Forge Refactor into one project-scoped CLI, then lets your AI development harness run the same traceable, approval-gated workflow from idea to production.

Forge AI does not install Claude Code, Kiro, Codex CLI, opencode, GitHub Copilot, or Cursor for you. It installs the Forge assets into your project and keeps the selected harness in its native format.

Start here

1. Install Forge AI globally.
2. Install Forge SDLC into the project you want to work on.
3. Run the Forge health check.
4. Open the project in a supported AI harness.
5. Start a workflow with /forge-sdlc <description> (or the harness-specific equivalent).
6. Answer questions, review artifacts, and approve each gate.
7. Resume, inspect, or recover the workflow from the same project at any time.

The complete source guide is available in the Forge SDLC User Guide.

Contents

• Requirements
• Install Forge AI
• Install Forge into a project
• Verify and maintain an installation
• Start Forge SDLC in your harness
• The complete A-to-Z workflow
• Choose the right scope
• Control an active workflow
• Understand the project files
• Team knowledge and customization
• Troubleshooting
• Full documentation map

Requirements

Runtime

• Node.js >=22.5.0 for Forge AI and the Workspace runtime.
• npm access to the public registry.
• At least one supported AI harness:
  • Claude Code
  • Kiro CLI
  • Kiro IDE
  • Codex CLI
  • opencode
  • GitHub Copilot (CLI & VS Code)
  • Cursor (IDE & CLI)
• bun on your PATH. The installed Forge harness hooks and TypeScript tools use Bun, even though Forge AI also includes a native SDLC runtime.

Each harness has additional authentication, model, permission, and trust requirements. Read the relevant harness guide before starting a team rollout.

Fix npm global-install permissions first, if needed

If npm install -g fails with EACCES under /usr/lib/node_modules, use a user-owned npm prefix instead of installing the package as root:

npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @knackforge-soft-solutions/forge-ai

Persist the PATH export in your shell profile. Verify the active prefix with npm config get prefix.

Install Forge AI

Install the public scoped package:

npm install -g @knackforge-soft-solutions/forge-ai
forge --version
forge --help

The package provides two equivalent executable names:

• forge — installer, doctor, status, update, and SDLC wrapper commands.
• forge-sdlc — compatibility alias for the SDLC runtime wrapper.

Install Forge into a project

Run installation from the project root or pass an explicit --project path. The installer is project-scoped: it writes Forge files into that project and does not install vendor applications.

Interactive installation

cd my-project
forge install

Choose:

• Forge SDLC for governed idea-to-production delivery.
• Forge Refactor for legacy analysis and modernization planning.
• Both agents to install both products.
• One or more harnesses: kiro, kiro-ide, claude, codex, opencode, copilot, or cursor.

The interactive installer selects Kiro CLI and Kiro IDE by default, but you can change the harness selection. It asks before replacing existing files.

Non-interactive installation

Non-interactive runs must specify products and harnesses:

forge install \
  --products sdlc \
  --harnesses claude \
  --project ./my-project \
  --yes

Install both products into multiple harnesses:

forge install \
  --products both \
  --harnesses kiro,kiro-ide,claude,codex,opencode,copilot,cursor \
  --project ./my-project \
  --yes

Use --json for automation:

forge install \
  --products sdlc \
  --harnesses codex \
  --project ./my-project \
  --yes \
  --json

What installation writes

For each selected harness, Forge copies the generated native harness tree and the shared forge-sdlc/ workspace shell into the project. The workspace shell is a sibling of .claude/, .kiro/, .codex/, .opencode/, .github/, or .cursor/; it is not nested inside the harness directory.

The installer also writes:

.forge/forge-ai.json       # installed package, products, harnesses, timestamp
.forge/backups/<timestamp>/ # backups created when --yes replaces files
forge-sdlc/                  # shared workflow state and workspace shell

Forge refuses to overwrite a different existing file unless replacement is explicitly allowed with --yes. Identical files are left untouched, making a repeat installation safe and idempotent.

Verify and maintain an installation

Run these commands from the target project:

forge doctor --project .
forge status --project .
forge doctor --project . --json
forge update

forge doctor validates the manifest and the selected harness roots. A healthy installation is necessary but does not replace the harness-specific doctor or a completed workflow gate.

To update Forge AI:

npm install -g @knackforge-soft-solutions/forge-ai
forge update

forge update checks the npm registry and prints the exact install command when a newer package exists. It does not modify project files automatically; run forge doctor after upgrading to confirm the installation.

Start Forge SDLC in your harness

After installation, open a session from the project root. The harness command is the primary user entry point for the full workflow:

| Harness | Start a session | Invoke Forge SDLC | |---|---|---| | Claude Code | claude | /forge-sdlc <description> | | Kiro CLI | kiro-cli chat | /forge-sdlc <description> | | Kiro IDE | Open the project in Kiro IDE | /forge-sdlc <description> | | Codex CLI | codex | $forge-sdlc <description> or /skills → forge-sdlc | | opencode | opencode | /forge-sdlc <description> | | GitHub Copilot (CLI & VS Code) | copilot or open in VS Code | /forge-sdlc <description> or @forge-sdlc-orchestrator-agent | | Cursor (IDE & CLI) | Open in Cursor IDE or run agent | /forge-sdlc <description> |

Examples:

/forge-sdlc Build a REST API for inventory management
/forge-sdlc Fix the login timeout bug
/forge-sdlc feature
/forge-sdlc compose "harden the deployment pipeline and add observability"

On Codex CLI, replace /forge-sdlc with $forge-sdlc.

Harness-specific usage notes

• Claude Code & Kiro: Standard /forge-sdlc <description> slash commands are discovered automatically from .claude/ or .kiro/. See the Claude Code guide and Kiro guide.
• Codex CLI: Skills use the $ prefix; run $forge-sdlc <description> or pick forge-sdlc from the /skills menu. See the Codex CLI guide.
• GitHub Copilot (CLI & VS Code): Works across standalone Copilot CLI (copilot) and VS Code agent mode from a shared .github/ shell and .forge-sdlc/ engine. Run /forge-sdlc <description> or mention @forge-sdlc-orchestrator-agent. See the GitHub Copilot guide.
• Cursor (IDE & CLI): Works across Cursor IDE and Cursor CLI (agent). Rules, subagents, and skills are installed in .cursor/ with automated onboarding in .cursor/rules/forge-sdlc-onboarding.mdc. Run /forge-sdlc <description>. See the Cursor guide.

The package wrapper is useful for direct runtime operations outside the harness conversation:

forge sdlc status
forge sdlc doctor
forge sdlc version
forge sdlc intent list
forge sdlc space list
forge-sdlc --help

Use the harness invocation for normal orchestration. Use the wrapper for status, diagnostics, version checks, and workspace commands when your harness does not expose the workflow skill directly.

The complete A-to-Z workflow

Forge SDLC is a five-phase, 32-stage lifecycle. It is deterministic about routing and state, but keeps human decisions at the points that change scope, requirements, design, implementation, or release risk.

A. Initialize the workspace and intent

The first Forge SDLC invocation automatically runs Initialization:

1. Workspace scaffold creates the active intent record directory.
2. Workspace detection classifies the project as greenfield or brownfield.
3. State initialization selects the stage plan, scope, depth, and test strategy, then writes forge-sdlc-state.md.

You do not run a separate scaffold command. The first intent is born in the active default space unless you switch or create another space first.

B. Ideate and frame the work

Ideation stages turn the initial description into an agreed problem and delivery boundary:

1. Intent Capture & Framing
2. Market Research
3. Feasibility & Constraints
4. Scope Definition
5. Team Formation
6. Rough Mockups
7. Approval & Handoff

Each applicable stage presents an interaction mode, produces artifacts, and ends at an approval gate. Conditional stages can be skipped when the selected scope does not include them.

C. Incept the solution

Inception converts the framed problem into an implementation plan:

1. Reverse Engineering — scans an existing codebase for brownfield work; skipped for greenfield projects when not applicable.
2. Practices Discovery — discovers project and team conventions.
3. Requirements Analysis — defines functional and non-functional needs.
4. User Stories — aligns personas, stories, and acceptance expectations.
5. Refined Mockups — elaborates user experience where applicable.
6. Application Design — defines components, services, interfaces, and ADRs.
7. Units Generation — decomposes the work into dependency-aware units.
8. Delivery Planning — sequences units into implementation Bolts.

The phase boundary verifies that required artifacts and traceability links are present before Construction begins.

D. Construct the solution Bolt by Bolt

Construction runs the implementation plan:

1. Functional Design
2. NFR Requirements
3. NFR Design
4. Infrastructure Design
5. Code Generation
6. Build and Test
7. CI Pipeline

A Bolt is one pass through the implementation stages for a unit or a dependency-linked group of units. The first Bolt is the walking skeleton: the smallest end-to-end slice that proves the architecture and is always gated. After it is approved, choose whether remaining Bolts run autonomously or with a gate for every Bolt. Independent Bolts may run in parallel batches; a failed Bolt always pauses for a retry, skip, or abort decision.

E. Operate and close the loop

Operation is conditional and may be skipped by smaller scopes:

1. Deployment Pipeline
2. Environment Provisioning
3. Deployment Execution
4. Observability Setup
5. Incident Response
6. Performance Validation
7. Feedback & Optimization

The final stage either completes the workflow or records the feedback needed to begin another Ideation cycle. Production deployment remains subject to your team's credentials, approvals, and operational controls.

What happens at every interactive stage

Most stages follow this loop:

1. Forge loads the stage definition, lead agent, prior artifacts, rules, and knowledge.
2. You choose Guide Me, Edit File, or Chat.
3. The agent asks questions, performs analysis, and writes the stage artifacts.
4. You review the completion summary and files in the intent record directory.
5. You Approve to advance or Request Changes to revise the stage.

Initialization runs deterministically without gates. Dispatched stages may run pipeline, subagent, or mob topologies, but still return to a human review gate before the workflow advances.

Choose the right scope

Scope controls which stages execute. Depth controls artifact detail. Test strategy controls the expected test volume and types. You can accept automatic detection or choose a scope explicitly.

| Scope | Stages | Default depth | Default test strategy | Use it for | |---|---:|---|---|---| | enterprise | 32 | Comprehensive | Comprehensive | Regulated, production-grade delivery | | feature | 32 | Standard | Standard | New features; full lifecycle | | mvp | 22 | Standard | Standard | Greenfield MVPs without full Operation | | poc | 8 | Minimal | Minimal | Fast feasibility proofs | | bugfix | 7 | Minimal | Minimal | Focused defect fixes | | refactor | 8 | Minimal | Minimal | Restructuring without behavior change | | infra | 13 | Standard | Standard | Infrastructure and deployment changes | | security-patch | 10 | Minimal | Minimal | CVE and vulnerability response | | workshop | 25 | Standard | Minimal | Facilitated multi-developer workshops |

Examples:

/forge-sdlc bugfix
/forge-sdlc --scope enterprise Build the payments platform
/forge-sdlc --depth comprehensive
/forge-sdlc --test-strategy minimal

For a tailored plan, use the adaptive composer:

/forge-sdlc compose "harden the deployment pipeline and add observability"
/forge-sdlc compose --report sonar.json
/forge-sdlc --new-scope "modernize the legacy billing boundary"

The composer proposes an execute/skip grid and waits for approval. It does not silently rewrite completed stages; in-flight recomposition applies only to pending stages and is audited.

See the full scope-to-stage matrix before choosing a scope for a large or regulated change.

Control an active workflow

Use these commands through the selected harness. On Codex CLI, replace /forge-sdlc with $forge-sdlc.

| Goal | Command | |---|---| | Resume the active intent | /forge-sdlc | | Start with a scope | /forge-sdlc feature | | Start from freeform intent | /forge-sdlc Build a payments API | | List or switch intents | /forge-sdlc intent / /forge-sdlc intent <name> | | List or switch spaces | /forge-sdlc space / /forge-sdlc space <name> | | Create a space | /forge-sdlc space-create <name> | | Show progress | /forge-sdlc --status | | Check the environment | /forge-sdlc --doctor | | Export a redacted diagnostic | /forge-sdlc --doctor --export | | Jump to a stage | /forge-sdlc --stage <slug-or-number> | | Run one stage without advancing | /forge-sdlc --stage <slug> --single | | Jump to a phase | /forge-sdlc --phase <name-or-number> | | Change active scope | /forge-sdlc --scope <name> | | Change depth | /forge-sdlc --depth <level> | | Change test strategy | /forge-sdlc --test-strategy <level> | | Inspect configuration | /forge-sdlc config list | | Set configuration | /forge-sdlc config set <key> <value> | | List plugins | /forge-sdlc plugin list | | Compose or reshape a plan | /forge-sdlc compose <request> |

Sessions, resume, redo, and recovery

Workflows span sessions. Start a new harness session in the same project and run /forge-sdlc; Forge reconstructs the active workflow from disk and offers the appropriate resume, redo, jump, or fresh-start action.

Read-only session views include:

/forge-sdlc-session-cost
/forge-sdlc-replay
/forge-sdlc-outcomes-pack

If a gate is stuck, first run --status, inspect the current stage artifact directory, and use --doctor. Request changes at the gate when the artifact needs revision. Use a stage jump or isolated stage runner only when you understand the traceability consequences; isolated stages do not advance the main workflow.

Understand the project files

Forge keeps methodology data separate from your application source:

forge-sdlc/
└── spaces/
    └── <space>/
        ├── memory/                 # affirmed org/team/project/phase practices
        ├── knowledge/              # team-owned shared knowledge
        ├── codekb/                 # reusable reverse-engineering evidence
        └── intents/
            └── <YYMMDD>-<label>/
                ├── forge-sdlc-state.md
                ├── audit/           # append-only per-clone audit shards
                ├── ideation/
                ├── inception/
                ├── construction/
                ├── operation/
                └── verification/

The intent record is the durable source of workflow progress. The state file tracks stage status and the audit trail records decisions, actions, approvals, revisions, and other lifecycle events. Stage artifacts are the reviewable outputs that feed later stages.

Commit the workflow artifacts your team needs for traceability. Keep machine-local cursors, temporary runtime files, credentials, and generated backups out of version control according to the selected harness guide.

Team knowledge and customization

Forge SDLC has two kinds of knowledge:

• Methodology knowledge ships with Forge and is replaced when the package is upgraded.
• Team knowledge belongs to your project or space and should be maintained by your team under forge-sdlc/spaces/<space>/knowledge/ and the active space's memory/ files.

Use team knowledge for architecture decisions, coding conventions, domain language, security standards, compliance constraints, and delivery policies. The workflow loads applicable knowledge into stage context and records the decisions that affect the run.

For deeper changes, see:

• Customization for settings, scopes, depth, permissions, agents, rules, and statusline.
• Knowledge for team and project conventions.
• Rules and the Learning Loop for reusable behavioral rules and learnings.
• Workshop Mode for multi-developer Bolt claims and handoffs.

Troubleshooting

Start with diagnostics:

forge doctor --project .
forge status --project . --json

Then check the matching symptom:

| Symptom | First action | |---|---| | EACCES during global npm install | Configure a user-owned npm prefix; see Requirements. | | Harness command is missing | Confirm the correct harness was selected and rerun forge doctor. | | bun is missing | Install Bun and ensure it is visible to non-interactive shell sessions. | | Workspace shell is missing | Reinstall the SDLC product into the project; forge-sdlc/ must be a project-root sibling of the harness directory. | | Existing Forge files block install | Review the files, then rerun with --yes only when backed-up replacement is intended. | | A gate needs more work | Choose Request Changes, revise the artifact, and approve again. | | Workflow state looks stale | Run --status and --doctor; inspect the intent state and audit files before editing anything. | | Context compaction interrupted a session | Start a new session in the same project and run /forge-sdlc to resume from the persisted state. | | A dispatched stage times out | Follow the troubleshooting recovery steps. |

Do not delete the intent state or audit trail as a first response. Those files are the evidence Forge uses to resume and reconcile the workflow.

Full documentation map

The package README is the operational starting point. The linked guide is the authoritative reference for the complete methodology and harness behavior.

Core user guide

| Guide | Coverage | |---|---| | Introduction | Methodology, architecture, key numbers, and guide map | | Getting Started | Harness prerequisites, provider setup, installation, and health checks | | Your First Workflow | Annotated end-to-end feature run | | Spaces and Intents | Multi-intent and multi-space workspace management | | Phases and Stages | All five phases, 32 stages, gates, and execution modes | | Scopes, Depth, and Test Strategy | Scope selection, adaptive composition, and the full routing matrix | | Agents | Agent roster, collaboration topology, and responsibilities | | Interaction Modes | Guide Me, Edit File, Chat, gates, revisions, and navigation | | Knowledge | Team, project, and domain knowledge | | Rules and the Learning Loop | Rules, learnings, and feedback into future runs | | State and Audit | State machine, audit events, and traceability | | Session Management | Resume, redo, jump, park, replay, and outcome reports | | CLI Commands | Complete invocation and flag reference | | Customization | Settings, agents, scopes, permissions, and extensions | | Artifacts Reference | Artifact directories, lifecycle, dependencies, and commit guidance | | Troubleshooting | State, hooks, locks, context, gates, and diagnostics | | Worked Examples | Bugfix and feature walkthroughs | | Skills and Runner Commands | Full, scope, stage, init, and reporting runners | | Glossary | Forge SDLC terminology | | Workshop Mode | Facilitated parallel Bolt delivery |

Harness guides

• Claude Code
• Kiro CLI
• Kiro IDE
• Codex CLI
• opencode
• GitHub Copilot (CLI & VS Code)
• Cursor (IDE & CLI)

Forge AI accelerators

• Forge SDLC accelerator
• Forge Refactor accelerator

License

MIT