Nairon Factory

AI-augmented SDLC workflow - from stakeholder call to deployed feature.

┌─────────────────────┐     ┌─────────────────────┐
│  Linear             │◄───►│  Beads (bd sync)    │
│  (kanban board)     │     │  (source of truth)  │
└─────────────────────┘     └──────────┬──────────┘
                                       │
                                       ▼
                            ┌─────────────────────┐
                            │  VPS Agents         │
                            │  (OpenClaw)         │
                            └──────────┬──────────┘
                                       │
                                       ▼
                            ┌─────────────────────┐
                            │  Telegram/Discord   │
                            │  (async Q&A)        │
                            └─────────────────────┘

What is this?

Nairon Factory is the methodology we use to build startups for clients - open-sourced so others can adopt it.

Philosophy: "Speed of impact, not speed of output."

Key Innovation: Async human-in-the-loop. Agents work autonomously on a VPS, ping humans via Telegram/Discord when they need decisions. No babysitting.

SDLC Phases

| Phase | Time | What Happens | |-------|------|--------------| | Requirements | 25% | Stakeholder call → PRD | | Planning | 35% | PRD → Technical plans + tickets | | Implementation | 15% | Plans → Working code with atomic commits | | Review | 25% | Code → Tested, reviewed, deployed |

Components

1. nf-tools CLI

State management for the workflow. Runs on VPS.

nf-tools state init "Project Name"
nf-tools phase create "Authentication"
nf-tools plan create 1 --name "OAuth Setup"
nf-tools progress

2. Agents

Specialized AI agents that do the actual work:

| Agent | Model | Purpose | |-------|-------|---------| | nf-interviewer | opus-4.6 | Clarifies requirements, generates PRDs | | nf-planner | gpt-5.3-codex | Creates wave-based technical plans | | nf-executor | gpt-5.3-codex (gemini-3.1-pro for frontend) | Implements plans with atomic commits | | nf-reviewer | gpt-5.3-codex | Tests, reviews, verifies completion | | nf-scout | gpt-5.3-codex-spark | Parallel codebase exploration (read-only) |

Model Strategy:

• opus-4.6: Interviewing (stakeholder empathy, ambiguity detection)
• gemini-3.1-pro: Frontend tasks (UI/UX intuition, component design)
• gpt-5.3-codex: Planning, implementation, review (superior code generation + technical reasoning)
• gpt-5.3-codex-spark: Scouting (fast parallel exploration)

3. Linear Integration

Beads syncs with Linear so you see tasks on a real kanban board.

4. Telegram Bot

Questions from agents appear in Telegram. Team discusses, answers with /answer.

Installation

npx nairon-factory@latest

This will prompt you to:

1. Choose your runtime (Claude Code or OpenCode)
2. Choose install location (global or local)

Manual Install

# Claude Code only
npx nairon-factory@latest --claude --global

# OpenCode only
npx nairon-factory@latest --opencode --global

# Both runtimes
npx nairon-factory@latest --all --global

# Local to current project
npx nairon-factory@latest --claude --local

Uninstall

# Uninstall from all runtimes (global)
npx nairon-factory@latest --uninstall --all --global

# Uninstall from specific runtime
npx nairon-factory@latest --uninstall --claude --global
npx nairon-factory@latest --uninstall --opencode --global

# Uninstall from local project
npx nairon-factory@latest --uninstall --claude --local

Connect Services (Optional)

# Link to Linear
nf config set linear_api_key <key>
nf config set linear_team_id <team>

# Link to Telegram
nf config set telegram_bot_token <token>
nf config set telegram_chat_id <chat>

Workflow

1. Start Project

Upload stakeholder call transcript → nf-interviewer clarifies → PRD generated

2. Plan Phases

nf-planner researches codebase → creates wave-based plans → tickets in Linear

3. Execute

nf-executor implements wave by wave → atomic commits → handles deviations:

• Tier 1-3: Auto-fix
• Tier 4: Asks human via Telegram

4. Review

nf-reviewer runs tests → AI code review → creates verification report

5. Deploy

If gates pass → merge PR → deploy

Directory Structure

.nf/
├── STATE.md              # Current project state
├── PRD.md                # Product requirements
├── config.json           # Linear/Telegram keys
├── phases/
│   ├── 1-authentication/
│   │   ├── CONTEXT.md    # Phase goal, scope, criteria
│   │   ├── PLAN-1.md     # Wave-based task breakdown
│   │   ├── SUMMARY-1.md  # Execution results
│   │   └── VERIFICATION.md
│   └── 2-dashboard/
└── questions/
    ├── q-123.json        # Pending questions
    └── answered/

Deviation Handling

When agents encounter unexpected situations:

| Tier | Severity | Action | |------|----------|--------| | 1 | Trivial | Auto-fix silently (typos, formatting) | | 2 | Minor | Auto-fix + note in summary | | 3 | Significant | Auto-fix + add blocker | | 4 | Major | STOP, ask human via Telegram |

Git Worktrees

For parallel phase execution:

# Create worktree for phase 2
git worktree add ../project-phase-2 -b phase/2-dashboard

# Agents work in separate worktrees
# Merge back when phase complete

Development

# Install dependencies
bun install

# Run CLI locally
bun run packages/cli/src/index.ts

# Build
bun run build

# Test
bun test

License

MIT