@akm1923main/init-project

v1.2.0

Published

7 days ago

An enterprise-grade project scaffolder for bootstrapping AI-OS (Artificial Intelligence Operating System) projects with a comprehensive suite of pre-built agent skills and development workflows.

0High
0Medium
0Low

akm1923main

scaffold initializer cli ai project

🚀 AI-OS Project Initializer

Scaffold production-grade, AI-driven projects in seconds. An 11-phase development pipeline with 14 specialist agents, 14 structured workflows, and a full state-tracking system — ready to go with one command.

🤔 Why AI-OS?

Building software with AI agents is powerful — but without structure, it becomes chaos. AI-OS gives you a deterministic, phase-based pipeline where every agent knows exactly what to do, what it needs, and what it produces.

⚡ Quick Start

No installation needed. Run directly with npx:

npx @akm1923main/init-project my-project

That's it. Open the generated folder and start with PROJECT_STATE.md.

Options

npx @akm1923main/init-project <project-name> [options]

Options:
  --path, -p <dir>   Target directory (default: current directory)
  --force, -f        Allow existing folder (adds missing items only)
  --help, -h         Show help

Examples

# Create in current directory
npx @akm1923main/init-project my-saas-app

# Create in a specific folder
npx @akm1923main/init-project my-saas-app --path ~/projects

# Add missing files to an existing project
npx @akm1923main/init-project my-saas-app --force

🔄 The AI-OS Pipeline

Every project follows an 11-phase sequential pipeline. Each phase is owned by a specialist agent that reads upstream artifacts and produces its own output.

flowchart TD
    START(["Project Created"]) --> P01

    subgraph PLAN ["Planning Phases"]
        P01["Phase 01: Idea Refinement\nAgent: Idea_Analyst\nOutput: IDEA.md"]
        P02["Phase 02: Business Analysis\nAgent: Business_Analyst\nOutput: PRODUCT_ANALYSIS.md"]
        P03["Phase 03: PRD Generation\nAgent: Product_Manager\nOutput: PRD.md"]
        P04["Phase 04: Architecture\nAgent: Architect\nOutput: ARCHITECTURE.md"]
    end

    subgraph BUILD ["Build Phases"]
        P05["Phase 05: Task Generation\nAgent: Staff_Engineer A\nOutput: TASK_PLAN.md"]
        P06["Phase 06: Task Execution\nAgent: Staff_Engineer B\nOutput: Code in 05_Project"]
    end

    subgraph QUALITY ["Quality Phases"]
        P07["Phase 07: Testing\nAgent: Testing_Engineer\nOutput: TEST_REPORT.md"]
        P08["Phase 08: Security Audit\nAgent: Security_Engineer\nOutput: SECURITY_AUDIT.md"]
        P09["Phase 09: Performance\nAgent: Performance_Engineer\nOutput: PERFORMANCE_REPORT.md"]
    end

    subgraph SHIP ["Ship Phases"]
        P10["Phase 10: DevOps\nAgent: DevOps_Engineer\nOutput: DEVOPS_PLAN.md"]
        P11["Phase 11: Deployment\nAgent: Deployment_Engineer\nOutput: DEPLOYMENT_GUIDE.md"]
    end

    P01 --> P02 --> P03 --> P04
    P04 --> P05 --> P06
    P06 --> P07 --> P08 --> P09
    P09 --> P10 --> P11
    P11 --> DONE(["Shipped!"])

    HELPER["Helper Agent\nActivate anytime"]
    DOCS["Documentation Writer\nCross-cutting"]
    REFACTOR["Refactor Specialist\nCross-cutting"]
    ORCHESTRATOR["Master Orchestrator\nCoordinates all agents"]

    style PLAN fill:#e3f2fd,stroke:#1565c0,color:#000
    style BUILD fill:#fff3e0,stroke:#e65100,color:#000
    style QUALITY fill:#e8f5e9,stroke:#2e7d32,color:#000
    style SHIP fill:#fce4ec,stroke:#c62828,color:#000
    style HELPER fill:#2d6a4f,stroke:#40916c,color:#fff
    style DOCS fill:#1d3557,stroke:#457b9d,color:#fff
    style REFACTOR fill:#6a040f,stroke:#9d0208,color:#fff
    style ORCHESTRATOR fill:#7b2cbf,stroke:#9d4edd,color:#fff
    style START fill:#f4a261,stroke:#e76f51,color:#000
    style DONE fill:#2a9d8f,stroke:#264653,color:#fff

🤖 Agents (14)

Every agent has a defined identity, inter-agent communication contracts, lifecycle integration, and quality checklists.

📐 Pipeline Agents (11)

These agents own specific phases and execute in sequence:

🔀 Cross-Cutting Agents (3)

These agents can be activated at any phase:

💡 New to AI-OS? Start with the 🧭 Helper Agent — it reads your project state and tells you exactly which agent to activate and what to do next.

📋 Workflows (14)

Each workflow defines a 6-stage lifecycle: Initialize → Validate → Execute → Verify → Close → State Sync.

Pipeline Workflows

| # | Workflow | Bound Agent | Phase | | :---- | :------------------------------------------ | :------------------- | :---- | | WF-01 | 💡idea_refinement_workflow.md | Idea_Analyst | 01 | | WF-02 | 📊business_analysis_workflow.md | Business_Analyst | 02 | | WF-03 | 📌prd_generation_workflow.md | Product_Manager | 03 | | WF-04 | 🏗️architecture_generation_workflow.md | Architect | 04 | | WF-05 | 📋task_generation_workflow.md | Staff_Engineer (A) | 05 | | WF-06 | ⚙️task_execution_workflow.md | Staff_Engineer (B) | 06 | | WF-07 | 🧪testing_workflow.md | Testing_Engineer | 07 | | WF-08 | 🔐security_audit_workflow.md | Security_Engineer | 08 | | WF-09 | ⚡performance_review_workflow.md | Performance_Engineer | 09 | | WF-10 | 🛠️devops_setup_workflow.md | DevOps_Engineer | 10 | | WF-11 | 🌐deployment_workflow.md | Deployment_Engineer | 11 |

Cross-Cutting Workflows

📂 Generated Project Structure

my-project/
├── 📊 PROJECT_STATE.md          ← Your project's single source of truth
├── 🏷️ VERSION.md                ← Version + framework metadata
├── 📄 README.md                 ← Project-level getting started guide
├── 🔒 .gitignore
├── 🔑 .env.example
│
├── 📚 01_Knowledge/             ← Reference docs, domain knowledge
│
├── 🤖 02_Skills/                ← Agent + workflow definitions (git-ignored)
│   ├── agents/                  ← 14 agent persona files
│   └── workflows/               ← 14 workflow files
│
├── 📄 03_Project_Info/          ← Agent output artifacts
│   ├── Idea_Analyst/            ← IDEA.md goes here
│   ├── Business_Analyst/        ← PRODUCT_ANALYSIS.md goes here
│   ├── Product_Manager/         ← PRD.md goes here
│   ├── Architect/               ← ARCHITECTURE.md goes here
│   ├── Testing_Engineer/        ← TEST_REPORT.md goes here
│   ├── Security_Engineer/       ← SECURITY_AUDIT.md goes here
│   ├── Performance_Engineer/    ← PERFORMANCE_REPORT.md goes here
│   └── DevOps_Engineer/         ← DEVOPS_PLAN.md goes here
│
├── 📋 04_Tasks/                 ← Task management
│   ├── TASK_PLAN.md             ← Master task list
│   ├── DEVELOPMENT_CHECKLIST.md ← Execution tracker
│   ├── PROGRESS_LOG.md          ← Chronological completion log
│   ├── RISK_REGISTER.md         ← Risk tracking
│   ├── TASKS/                   ← Individual task files
│   │   └── TEMPLATE_TASK.md     ← Task template
│   └── ARCHIVE/                 ← Completed task archive
│
├── 💻 05_Project/               ← Your actual implementation code
│   └── README.md
│
├── 📘 06_Documentation/         ← Generated system docs
│
└── 🧭 07_state/                 ← State tracking & decisions
    ├── CHANGELOG.md             ← Version-by-version changes
    ├── DECISIONS.md             ← Every significant decision
    ├── ADR.md                   ← Architecture Decision Records
    ├── KNOWN_ISSUES.md          ← Issue tracker
    └── INCIDENT_LOG.md          ← Production incident log

🎯 How to Use (Step by Step)

1. Create Your Project

npx @akm1923main/init-project my-project
cd my-project

2. Check Your Starting Point

Open PROJECT_STATE.md — it shows you're at Phase 01 with Idea_Analyst as the current agent.

3. Activate the Current Agent

Tell your AI assistant to act as the Idea_Analyst agent. Point it to:

02_Skills/agents/Idea_Analyst.md — agent identity and rules
02_Skills/workflows/idea_refinement_workflow.md — the workflow to follow

4. Work Through the Pipeline

Each agent:

Reads its upstream artifacts
Follows its bound workflow (6 stages)
Produces its output artifact
Updates PROJECT_STATE.md and PROGRESS_LOG.md
Hands off to the next agent

5. Lost? Use the Helper Agent

At any point, activate the 🧭 Helper Agent (02_Skills/agents/Helper_Agent.md). It will:

Read all your project state files
Tell you exactly where you are
Tell you what to do next
Flag any drift or skipped phases

📊 State Tracking System

AI-OS tracks everything automatically:

🏗️ Architecture Principles

⚙️ How It Works Internally

flowchart LR
    A["npx init-project my-app"] --> B["Download from npm"]
    B --> C["Run index.js"]
    C --> D["Parse CLI args"]
    D --> E["Create folder structure"]
    E --> F["Copy 02_Skills\nagents + workflows"]
    F --> G["Generate state files\nPROJECT_STATE, VERSION, etc."]
    G --> H["Project ready!"]

    style A fill:#f4a261,stroke:#e76f51,color:#000
    style H fill:#2a9d8f,stroke:#264653,color:#fff

npx downloads the latest version from npm
index.js parses arguments and creates the folder skeleton
Bundled templates (templates/02_Skills/) are copied as-is — 14 agents, 14 workflows
Inline templates generate all state tracking files with initial content
Zero dependencies — pure Node.js, no npm packages required

🐍 Default: Python + uv

The generated project defaults to Python with uv for package management:

cd 05_Project
uv venv
uv pip install <package>

You can use any language or framework — just put your code in 05_Project/.

🤝 Contributing

Contributions are welcome! If you have ideas for:

🤖 New agent personas
📋 New workflows
🔧 Improvements to templates or scaffolding

Please open an issue or submit a pull request on our GitHub repository.

📄 License

Built with ❤️ for AI-driven development

AI-OS 14 agents · 14 workflows · 11 phases · Zero dependencies