> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SpecForge Projects

> 5-stage project management conductor that guides software projects from natural language intent to approved execution.

<Info>
  **ArgentOS Business** -- This feature is part of ArgentOS Business. The architecture is documented here for all users, but full functionality requires a Business license. [Learn more about Business](/business)
</Info>

## Overview

SpecForge is ArgentOS's project management intake workflow. It detects when a user is describing a new software project, activates a 5-stage conductor that guides the conversation from vague intent through a structured intake interview, produces a product requirements document (PRD), obtains approval, and then generates an execution plan with team assignments and task dependencies.

The system is designed to turn "I need to build an app that..." into a fully scoped project with atomic tasks, lane assignments, and dependency chains -- all through natural conversation.

```mermaid theme={null}
flowchart LR
    A["'I need to build a CRM...'"] --> B[Project Type Gate]
    B --> C[Intake Interview]
    C --> D[Draft Review]
    D --> E[Awaiting Approval]
    E -->|Approved| F[Execution]
    E -->|Changes| D
```

## The 5 Stages

<Steps>
  <Step title="Project Type Gate">
    When SpecForge detects a project kickoff signal, the first step is classifying the project type:

    | Type           | Detection Signals                                       | Implications                     |
    | -------------- | ------------------------------------------------------- | -------------------------------- |
    | **Greenfield** | "brand new", "from scratch", "new project"              | Full intake required             |
    | **Brownfield** | "existing project", "add feature", "refactor", "legacy" | Existing codebase context needed |
    | **Unknown**    | Ambiguous signals                                       | SpecForge asks for clarification |
  </Step>

  <Step title="Intake Interview">
    The conductor tracks coverage across 7 intake dimensions, asking targeted questions for any dimension not yet covered:

    | Dimension             | What It Covers                         |
    | --------------------- | -------------------------------------- |
    | **Problem**           | What problem does this solve?          |
    | **Users**             | Who will use it?                       |
    | **Success**           | How do we measure success?             |
    | **Constraints**       | What limits exist?                     |
    | **Scope**             | What's in scope?                       |
    | **Non-Scope**         | What's explicitly out?                 |
    | **Technical Context** | Technical requirements and preferences |
  </Step>

  <Step title="Draft Review">
    SpecForge generates a PRD (Product Requirements Document). The `draftVersion` counter tracks revisions:

    * **v1**: Initial draft from intake data
    * **v2+**: Revised based on user feedback
  </Step>

  <Step title="Awaiting Approval">
    The user reviews the final draft and provides a decision:

    * **Approve**: "looks good", "ship it", "proceed", "go ahead"
    * **Changes**: "not approved", "changes needed", "revise"
  </Step>

  <Step title="Approved Execution">
    Upon approval, SpecForge triggers the execution phase:

    1. **Team lane assignment** -- assigns agents to roles
    2. **Task generation** -- creates atomic tasks with dependency chains
    3. **Methodology binding** -- loads methodology docs for reference
    4. **Execution kickoff** -- hands tasks to the execution worker
  </Step>
</Steps>

## Kickoff Detection

SpecForge detects project kickoff signals from natural language using a multi-signal scoring system:

### Explicit Triggers

Direct requests like "use SpecForge", "spec forge this", or "specforge this" always trigger.

### Starter + Domain Detection

Conversational starters ("I need", "we need", "let's", "can you") combined with domain nouns ("app", "tool", "api", "saas", "project", "platform", "system") trigger the conductor.

### Action + Domain Scoring

Action verbs ("build", "create", "plan", "spec", "architect", "design", "scope") combined with domain nouns also trigger, even without conversational starters.

## Team Lane Assignments

When a project is approved, SpecForge assigns agents to team lanes:

```typescript theme={null}
type LaneAssignment = {
  lead: string;      // Project lead / architect
  backend: string;   // Backend development
  frontend: string;  // Frontend development
  qa: string;        // Quality assurance / testing
};
```

<Tip>
  In multi-agent deployments, different family agents can be assigned to different lanes. In single-agent mode, the main agent covers all lanes.
</Tip>

## Session Persistence

SpecForge guide sessions are persisted to PostgreSQL for resume capability. If the gateway restarts or the conversation is interrupted, the session state is restored from PG.

## Auto-Scaffold

SpecForge includes an optional auto-scaffold feature (disabled by default) that can generate initial project structure:

```bash theme={null}
# Enable via environment variable
ARGENT_SPECFORGE_AUTOSCAFFOLD=1
```

When enabled, approved projects get initial directory structure, configuration files, and boilerplate code generated automatically.

## Configuration

SpecForge is enabled by default when the gateway starts. Auto-scaffold is controlled separately:

```bash theme={null}
# Auto-scaffold (project file generation) — off by default
ARGENT_SPECFORGE_AUTOSCAFFOLD=1
```