@akm1923main/init-project 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Kumar Bind (Akm1923)
+
+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,48 +1,369 @@
-# create-ai-project
+# 🚀 AI-OS Project Initializer
 
-A CLI that scaffolds an **AI-OS** project structure.
+[![npm version](https://img.shields.io/npm/v/@akm1923main/init-project.svg)](https://www.npmjs.com/package/@akm1923main/init-project)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Key guarantee (your requirement)
+> **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.
 
-When you initialize a project, the generated project will contain **02_Skills/** with the **exact same files and content** that ship inside this CLI package.
+---
 
-- No external copy paths
-- No tiny placeholders
-- The standard skills are bundled under: `templates/02_Skills/`
+## 🤔 Why AI-OS?
 
-> Note: By your preference, generated projects include `02_Skills/` in `.gitignore`.
+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.
 
-## Usage (local dev)
+| Without AI-OS                          | With AI-OS                                               |
+| :------------------------------------- | :------------------------------------------------------- |
+| ❌ Hours of boilerplate setup          | ✅**One command, full structure**                  |
+| ❌ Agents running without coordination | ✅**11-phase pipeline with strict ordering**       |
+| ❌ No state tracking between sessions  | ✅**Evolution ledger + resume logic**              |
+| ❌ Inconsistent project structures     | ✅**Enterprise-grade, standardized architecture**  |
+| ❌ Lost context when switching agents  | ✅**Inter-agent contracts with explicit handoffs** |
+| ❌ No idea what to do next             | ✅**🧭 Helper Agent tells you exactly**            |
+
+---
+
+## ⚡ Quick Start
+
+No installation needed. Run directly with `npx`:
+
+```bash
+npx @akm1923main/init-project my-project
+```
+
+**That's it.** Open the generated folder and start with `PROJECT_STATE.md`.
+
+### Options
+
+```bash
+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
 
 ```bash
-cd "C:\Users\hp\Desktop\New folder\create-ai-project"
-npm link
-create-ai-project my-project
+# 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.
+
+```mermaid
+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:
+
+| Phase | Agent                                     | Role                                                 | Produces                      |
+| :---- | :---------------------------------------- | :--------------------------------------------------- | :---------------------------- |
+| 01    | 💡**Idea_Analyst**                  | Refines raw ideas into structured concepts           | `IDEA.md`                   |
+| 02    | 📊**Business_Analyst**              | Evaluates commercial viability and market fit        | `PRODUCT_ANALYSIS.md`       |
+| 03    | 📌**Product_Manager**               | Generates detailed PRD with functional requirements  | `PRD.md`                    |
+| 04    | 🏗️**Architect**                   | Designs system architecture, tech stack, data models | `ARCHITECTURE.md`           |
+| 05    | 📋**Staff_Engineer** *(Mode A)*   | Decomposes architecture into atomic tasks            | `TASK_PLAN.md` + task files |
+| 06    | ⚙️**Staff_Engineer** *(Mode B)* | Implements each task against architecture            | Code in `05_Project/`       |
+| 07    | 🧪**Testing_Engineer**              | Validates code against PRD requirements              | `TEST_REPORT.md`            |
+| 08    | 🔐**Security_Engineer**             | STRIDE threat modeling + OWASP compliance audit      | `SECURITY_AUDIT.md`         |
+| 09    | ⚡**Performance_Engineer**          | Identifies bottlenecks, evaluates scalability        | `PERFORMANCE_REPORT.md`     |
+| 10    | 🛠️**DevOps_Engineer**             | Designs CI/CD, infrastructure, containerization      | `DEVOPS_PLAN.md`            |
+| 11    | 🌐**Deployment_Engineer**           | Platform-specific deployment + runbooks              | `DEPLOYMENT_GUIDE.md`       |
+
+### 🔀 Cross-Cutting Agents (3)
+
+These agents can be activated at **any phase**:
+
+| Agent                            | Role                                                  | When to Use                               |
+| :------------------------------- | :---------------------------------------------------- | :---------------------------------------- |
+| 🎯**Master_Orchestrator**  | Coordinates multi-agent workflows, resolves conflicts | Complex multi-phase operations            |
+| 📘**Documentation_Writer** | Generates system documentation from project artifacts | Any phase that needs docs                 |
+| 🔁**Refactor_Specialist**  | Code quality improvements, architectural cleanup      | During or after implementation            |
+| 🧭**Helper_Agent**         | Reads project state and tells you what to do next     | **Anytime you're lost or confused** |
+
+> **💡 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
+
+| Workflow                             | Purpose                                                      |
+| :----------------------------------- | :----------------------------------------------------------- |
+| 📘`documentation_workflow.md`      | System documentation generation                              |
+| 🔁`refactor_workflow.md`           | Code quality improvement cycles                              |
+| 🏛️`workflow_governance_rules.md` | Supreme governance: arbitration, drift detection, escalation |
+
+---
+
+## 📂 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
 ```
 
-## Usage (npx — the way you want)
+---
 
-After you publish this package to npm:
+## 🎯 How to Use (Step by Step)
+
+### 1. Create Your Project
 
 ```bash
-npx create-ai-project my-project
+npx @akm1923main/init-project my-project
+cd my-project
 ```
 
-## Options
+### 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:
+
+1. Reads its upstream artifacts
+2. Follows its bound workflow (6 stages)
+3. Produces its output artifact
+4. Updates `PROJECT_STATE.md` and `PROGRESS_LOG.md`
+5. 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:
+
+| File                                  | What It Tracks                                                |
+| :------------------------------------ | :------------------------------------------------------------ |
+| `PROJECT_STATE.md`                  | 📊 Current phase, agent, pipeline status, resume instructions |
+| `04_Tasks/PROGRESS_LOG.md`          | 📜 Chronological record of every phase completion             |
+| `04_Tasks/TASK_PLAN.md`             | 📋 All tasks with priority, complexity, dependencies          |
+| `04_Tasks/DEVELOPMENT_CHECKLIST.md` | ✅ Per-task completion tracker                                |
+| `04_Tasks/RISK_REGISTER.md`         | ⚠️ Project risks with severity classification               |
+| `07_state/CHANGELOG.md`             | 📜 Version-by-version change history                          |
+| `07_state/DECISIONS.md`             | 🧭 Every decision with phase/agent attribution                |
+| `07_state/ADR.md`                   | 🏛️ Immutable architecture decision records                  |
+| `07_state/KNOWN_ISSUES.md`          | 🐛 Issue tracker with severity levels                         |
+| `07_state/INCIDENT_LOG.md`          | 🚨 Production incident log with response protocol             |
+
+---
+
+## 🏗️ Architecture Principles
+
+| Principle                      | Implementation                                        |
+| :----------------------------- | :---------------------------------------------------- |
+| **Phase-Based Pipeline** | 11 sequential phases with strict ordering             |
+| **Agent Ownership**      | Each phase owned by exactly one specialist agent      |
+| **Artifact Contracts**   | Explicit input/output schemas between agents          |
+| **State Persistence**    | Evolution ledger tracks all progress across sessions  |
+| **Resume Safety**        | Any agent can resume from the last recorded state     |
+| **Drift Detection**      | Governance rules detect and flag inconsistencies      |
+| **Self-Validating**      | Each workflow verifies its own outputs before closing |
+
+---
+
+## ⚙️ How It Works Internally
+
+```mermaid
+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
+```
+
+1. **`npx`** downloads the latest version from npm
+2. **`index.js`** parses arguments and creates the folder skeleton
+3. **Bundled templates** (`templates/02_Skills/`) are copied as-is — 14 agents, 14 workflows
+4. **Inline templates** generate all state tracking files with initial content
+5. **Zero dependencies** — pure Node.js, no npm packages required
+
+---
+
+## 🐍 Default: Python + uv
+
+The generated project defaults to Python with [uv](https://github.com/astral-sh/uv) for package management:
 
 ```bash
-create-ai-project <project-name> [--path <targetDir>] [--force]
+cd 05_Project
+uv venv
+uv pip install <package>
 ```
 
-## What gets created at init
-- Folder skeleton (AI-OS)
-- `PROJECT_STATE.md`, `.gitignore`, `.env.example`, `VERSION.md`
-- `04_Tasks/*` and `07_state/*`
-- **02_Skills/** copied from bundled templates
+> 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](https://github.com/Akm1923/init-project).
+
+---
+
+## 📄 License
+
+MIT © [Amit Kumar Bind](https://github.com/Akm1923)
+
+---
+
+---
 
-### Empty docs behavior (by design)
-Initializer creates folders but does NOT create empty markdown files under:
-- `03_Project_Info/*` (folders only)
-- `06_Documentation/*` (folder only)
+**Built with ❤️ for AI-driven development**
 
-Agents/workflows generate/update those later.
+*AI-OS 14 agents · 14 workflows · 11 phases · Zero dependencies*

package/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// © 2026 Amit Kumar Bind (Akm1923). MIT License.
+// https://github.com/Akm1923/init-project
 
 /**
  * create-ai-project
@@ -94,11 +96,11 @@ function main() {
     console.log(
       normalizeLines(
         `create-ai-project - AI-OS project initializer\n\n` +
-          `Usage:\n  create-ai-project <project-name> [--path <targetDir>] [--force]\n\n` +
-          `Options:\n` +
-          `  --path, -p   Target directory (default: current directory)\n` +
-          `  --force, -f  Allow existing folder (will only add missing items)\n` +
-          `  --help, -h   Show help\n`
+        `Usage:\n  create-ai-project <project-name> [--path <targetDir>] [--force]\n\n` +
+        `Options:\n` +
+        `  --path, -p   Target directory (default: current directory)\n` +
+        `  --force, -f  Allow existing folder (will only add missing items)\n` +
+        `  --help, -h   Show help\n`
       )
     );
     process.exit(args.help ? 0 : 1);
@@ -144,11 +146,11 @@ function main() {
   const now = new Date().toISOString();
 
   // Root files
-  writeFileIfNotExists(path.join(projectPath, 'VERSION.md'), `# VERSION\n\n0.1.0\n`);
+  writeFileIfNotExists(path.join(projectPath, 'VERSION.md'), `# 🏷️ VERSION\n\n> Track your project version and the AI-OS framework powering it.\n\n---\n\n## 📦 Current Version\n\n**v0.1.0**\n\n---\n\n## 🤖 Framework Details\n\n| Field | Value |\n|:------|:------|\n| Framework | AI-OS |\n| Version | 1.2.0 |\n| Pipeline Phases | 11 Sequential |\n| Active Agents | 14 |\n| Workflow Definitions | 14 |\n\n---\n\n## 📜 Version History\n\n| Version | Date | Description |\n|:--------|:-----|:------------|\n| v0.1.0 | ${now} | 🎉 Initial project scaffold |\n\n---\n\n*Updated automatically by AI-OS agents during phase transitions.*\n`);
 
   writeFileIfNotExists(
     path.join(projectPath, 'PROJECT_STATE.md'),
-    `# PROJECT_STATE\n\nCreated: ${now}\n\n## Purpose\n- \n\n## Current status\n- Phase: discovery / build / test / ship\n\n## Top priorities\n- [ ]\n\n## Key decisions\n- See: 07_state/DECISIONS.md\n- See: 07_state/ADR.md\n`
+    `# 📊 PROJECT STATE — Evolution Ledger\n\n> **This is your project's single source of truth.** Every agent reads this file first to know where the project stands.\n\n---\n\n## 🆔 Project Identity\n\n| Field | Value |\n|:------|:------|\n| **Project Name** | ${projectName} |\n| **Created** | ${now} |\n| **Framework** | AI-OS v1.2.0 |\n| **Current Phase** | 01 — Idea Refinement |\n| **Current Agent** | Idea_Analyst |\n| **Pipeline Status** | ⏳ Not Started |\n\n---\n\n## 🔄 Phase Tracker\n\n> Each row represents one pipeline phase. Agents update this table as they complete their work.\n\n| # | Phase | Agent | Status | Output Artifact | Completed |\n|:--|:------|:------|:-------|:----------------|:----------|\n| 01 | 💡 Idea Refinement | Idea_Analyst | ⏳ Not Started | IDEA.md | — |\n| 02 | 📊 Business Analysis | Business_Analyst | ⏳ Not Started | PRODUCT_ANALYSIS.md | — |\n| 03 | 📌 PRD Generation | Product_Manager | ⏳ Not Started | PRD.md | — |\n| 04 | 🏗️ Architecture | Architect | ⏳ Not Started | ARCHITECTURE.md | — |\n| 05 | 📋 Task Generation | Staff_Engineer (A) | ⏳ Not Started | TASK_PLAN.md | — |\n| 06 | ⚙️ Task Execution | Staff_Engineer (B) | ⏳ Not Started | Code in 05_Project/ | — |\n| 07 | 🧪 Testing | Testing_Engineer | ⏳ Not Started | TEST_REPORT.md | — |\n| 08 | 🔐 Security Audit | Security_Engineer | ⏳ Not Started | SECURITY_AUDIT.md | — |\n| 09 | ⚡ Performance | Performance_Engineer | ⏳ Not Started | PERFORMANCE_REPORT.md | — |\n| 10 | 🚀 DevOps | DevOps_Engineer | ⏳ Not Started | DEVOPS_PLAN.md | — |\n| 11 | 🌐 Deployment | Deployment_Engineer | ⏳ Not Started | DEPLOYMENT_GUIDE.md | — |\n\n---\n\n## 🚧 Blocking Issues\n\n> *None at this time.*\n\n---\n\n## 📎 Key References\n\n- 📝 Decisions → \`07_state/DECISIONS.md\`\n- 🏛️ Architecture Decisions → \`07_state/ADR.md\`\n- 📜 Change History → \`07_state/CHANGELOG.md\`\n\n---\n\n## 🔁 How to Resume\n\n> If the project was paused or context was lost, follow these steps:\n\n1. Read **this file** to identify the current phase and agent\n2. Read the last entry in \`04_Tasks/PROGRESS_LOG.md\` for context\n3. Activate the agent listed under **Current Agent**\n4. The agent will read its required upstream artifacts and continue\n\n---\n\n*Last updated: ${now}*\n`
   );
 
   // You explicitly want skills ignored in generated projects.
@@ -165,33 +167,33 @@ function main() {
   // Tasks + state (these are useful even if empty)
   writeFileIfNotExists(
     path.join(projectPath, '04_Tasks', 'TASK_PLAN.md'),
-    `# TASK_PLAN\n\n## Milestones\n\n## Tasks\n- [ ]\n\nCreated: ${now}\n`
+    `# 📋 TASK PLAN\n\n> **Master task list for implementation.** Generated by Staff_Engineer (Mode A) during Phase 05.\n> Each task maps to an architecture component and traces back to a PRD requirement.\n\n---\n\n## 📊 Generation Status\n\n| Field | Value |\n|:------|:------|\n| Generated By | Staff_Engineer (Mode A) |\n| Architecture Source | \`03_Project_Info/Architect/ARCHITECTURE.md\` |\n| PRD Source | \`03_Project_Info/Product_Manager/PRD.md\` |\n| Total Tasks | 0 |\n| Critical Path Tasks | 0 |\n| Status | ⏳ Not Generated |\n| Created | ${now} |\n\n---\n\n## 📦 Task Summary\n\n> Tasks are populated automatically during Phase 05 — Task Generation.\n\n| Task ID | Title | Priority | Complexity | Dependencies | Status |\n|:--------|:------|:---------|:-----------|:-------------|:-------|\n| — | *Awaiting generation* | — | — | — | ⏳ |\n\n---\n\n## 🔥 Critical Path\n\n> *Not yet identified. Will be marked during Task Generation.*\n\n---\n\n## 🔗 Requirement Traceability\n\n> Every functional requirement (FR) from the PRD must map to at least one task.\n\n| FR ID | Task ID(s) | Coverage |\n|:------|:-----------|:---------|\n| — | — | — |\n\n---\n\n*This file is auto-populated. Do not edit manually unless correcting task generation output.*\n`
   );
   writeFileIfNotExists(
     path.join(projectPath, '04_Tasks', 'DEVELOPMENT_CHECKLIST.md'),
-    `# DEVELOPMENT_CHECKLIST\n\n- [ ] Repo initialized (git)\n- [ ] Build/run instructions exist\n- [ ] Tests added\n- [ ] Lint/format configured\n- [ ] Security basics (secrets, deps)\n`
+    `# ✅ DEVELOPMENT CHECKLIST\n\n> **Your task execution tracker.** Work through tasks top-to-bottom in dependency order.\n> Staff_Engineer (Mode B) updates this during Phase 06.\n\n---\n\n## 📋 Execution Order\n\n> Tasks listed in dependency-resolved order. **Execute top-to-bottom. Never skip.**\n\n| # | Task ID | Title | Depends On | Status |\n|:--|:--------|:------|:-----------|:-------|\n| — | — | *Awaiting task generation* | — | ⏳ |\n\n---\n\n## 📊 Completion Summary\n\n| Metric | Count |\n|:-------|:------|\n| Total Tasks | 0 |\n| ✅ Completed | 0 |\n| 🔄 In Progress | 0 |\n| 🚧 Blocked | 0 |\n| ⏳ Remaining | 0 |\n\n---\n\n## 🎯 Phase Milestones\n\n- [ ] Phase 05 — Task Generation complete\n- [ ] Phase 06 — All tasks implemented\n- [ ] Phase 06 — All acceptance criteria verified\n- [ ] Phase 06 — All state files synced\n\n---\n\n*Created: ${now}*\n`
   );
   writeFileIfNotExists(
     path.join(projectPath, '04_Tasks', 'PROGRESS_LOG.md'),
-    `# PROGRESS_LOG\n\n## ${now}\n- Project created\n`
+    `# 📜 PROGRESS LOG\n\n> **Chronological record of every phase completion.** Each agent appends an entry when finishing its work.\n\n---\n\n## 📝 Entry Format\n\n> Use this structure for every new entry:\n\n\`\`\`\n## YYYY-MM-DDTHH:MM:SSZ\n\n**Phase XX: Phase Name** — Status\n- 🤖 Agent: agent_name\n- 📄 Artifact: output artifact\n- 📌 Outcomes: summary\n- ⚠️ Issues: count or none\n- ➡️ Next: next_agent (Phase XX)\n\`\`\`\n\n---\n\n## ${now}\n\n**Phase 00: Project Initialization** — ✅ Completed\n- 🤖 Agent: CLI (create-ai-project)\n- 📄 Artifact: Project scaffold\n- 📌 Outcomes: Folder structure created, 14 agents + 14 workflows deployed\n- ⚠️ Issues: None\n- ➡️ Next: Idea_Analyst (Phase 01)\n`
   );
   writeFileIfNotExists(
     path.join(projectPath, '04_Tasks', 'RISK_REGISTER.md'),
-    `# RISK_REGISTER\n\n| Risk | Impact | Likelihood | Mitigation | Owner | Status |\n|---|---|---|---|---|---|\n|  |  |  |  |  |  |\n`
+    `# ⚠️ RISK REGISTER\n\n> **Track and manage project risks across all phases.** Each agent flags risks during its work.\n\n---\n\n## 🎯 Severity Scale\n\n| Level | Emoji | Description |\n|:------|:------|:------------|\n| Critical | 🔴 | Blocks deployment — immediate action required |\n| High | 🟠 | Significant impact — must address before release |\n| Medium | 🟡 | Notable concern — schedule for resolution |\n| Low | 🟢 | Minor issue — track and monitor |\n\n---\n\n## 🔴 Active Risks\n\n| ID | Risk Description | Severity | Likelihood | Impact | Mitigation | Owner | Phase | Status |\n|:---|:-----------------|:---------|:-----------|:-------|:-----------|:------|:------|:-------|\n| — | *No risks identified yet* | — | — | — | — | — | — | — |\n\n---\n\n## ✅ Resolved Risks\n\n| ID | Risk | Resolution | Date Resolved |\n|:---|:-----|:-----------|:--------------|\n| — | *None yet* | — | — |\n\n---\n\n*Created: ${now}*\n`
   );
   writeFileIfNotExists(
     path.join(projectPath, '04_Tasks', 'TASKS', 'TEMPLATE_TASK.md'),
-    `# TASK: <title>\n\n## Goal\n\n## Acceptance criteria\n\n## Steps\n\n## Notes\n`
+    `# 🎯 Task XXX: <Title>\n\n> *Copy this template for each new task. Replace XXX with the task number.*\n\n---\n\n## 📌 Quick Info\n\n| Field | Value |\n|:------|:------|\n| **Status** | ⏳ Not Started / 🔄 In Progress / ✅ Complete / 🚧 Blocked |\n| **Priority** | 🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low |\n| **Complexity** | Low / Medium / High |\n\n---\n\n## 🔗 Dependencies\n\n> List tasks that must be completed before this one can start.\n\n- TASK_XXX — *(describe what it provides)*\n\n---\n\n## 📝 Description\n\n> Clear, atomic description of what to implement. One concern per task.\n\n*(Write here)*\n\n---\n\n## ✅ Acceptance Criteria\n\n> All must pass before marking this task complete.\n\n- [ ] Criterion 1\n- [ ] Criterion 2\n\n---\n\n## 🛠️ Implementation Notes\n\n> Guidance from architecture. **Do NOT exceed this scope.**\n\n*(Write here)*\n\n---\n\n## 📂 Files to Create / Modify\n\n- \`05_Project/path/to/file.ext\`\n\n---\n\n## 🏗️ Architecture Reference\n\n> Which section of ARCHITECTURE.md does this task implement?\n\n*(Reference here)*\n\n---\n\n## 📊 Completion Log\n\n| Field | Value |\n|:------|:------|\n| Started | — |\n| Completed | — |\n| Drift Detected | None |\n| Files Changed | — |\n`
   );
 
-  writeFileIfNotExists(path.join(projectPath, '07_state', 'CHANGELOG.md'), `# CHANGELOG\n\n## Unreleased\n-\n`);
-  writeFileIfNotExists(path.join(projectPath, '07_state', 'DECISIONS.md'), `# DECISIONS\n\n## ${now}\n- Initial scaffold\n`);
+  writeFileIfNotExists(path.join(projectPath, '07_state', 'CHANGELOG.md'), `# 📜 CHANGELOG\n\n> **All notable changes to this project.** Format follows [Keep a Changelog](https://keepachangelog.com/).\n\n---\n\n## [Unreleased]\n\n### ➕ Added\n\n- *(Next changes go here)*\n\n### 🔄 Changed\n\n### 🐛 Fixed\n\n### 🗑️ Removed\n\n---\n\n## [0.1.0] — ${now}\n\n### ➕ Added\n\n- 🎉 Project initialized with AI-OS v1.2.0 framework\n- 🤖 14 agent definitions deployed\n- 🔄 14 workflow definitions deployed\n- 📊 State tracking infrastructure created\n- 📋 Task management templates deployed\n\n---\n\n*Agents append to this file after significant changes.*\n`);
+  writeFileIfNotExists(path.join(projectPath, '07_state', 'DECISIONS.md'), `# 🧭 DECISIONS\n\n> **Every significant decision — who made it, why, and what it affects.**\n> For architectural decisions, also create an entry in \`ADR.md\`.\n\n---\n\n## 📝 Decision Template\n\n> Copy this block for each new decision:\n\n| Field | Value |\n|:------|:------|\n| **Decision ID** | DEC-XXX |\n| **Date** | — |\n| **Phase** | — |\n| **Agent** | — |\n| **Decision** | — |\n| **Rationale** | — |\n| **Impact** | — |\n| **ADR Link** | ADR-XXX *(if architectural)* |\n\n---\n\n## DEC-001\n\n| Field | Value |\n|:------|:------|\n| **Decision ID** | DEC-001 |\n| **Date** | ${now} |\n| **Phase** | Initialization |\n| **Agent** | CLI (create-ai-project) |\n| **Decision** | Project scaffolded with AI-OS v1.2.0 framework |\n| **Rationale** | Standard initialization for structured AI-driven development |\n| **Impact** | 11-phase pipeline established with 14 agents |\n| **ADR Link** | ADR-0001 |\n`);
   writeFileIfNotExists(
     path.join(projectPath, '07_state', 'ADR.md'),
-    `# ADR (Architecture Decision Records)\n\n### ADR-0001: <Title>\n- Date: ${now}\n- Status: Proposed | Accepted | Superseded\n\n#### Context\n\n#### Decision\n\n#### Consequences\n\n---\n`
+    `# 🏛️ Architecture Decision Records (ADR)\n\n> **Immutable records of architectural choices.** Once accepted, an ADR is never edited — only superseded by a new one.\n\n---\n\n## 📝 ADR Template\n\n> Copy this block for each new architecture decision:\n\n### ADR-XXXX: <Title>\n\n| Field | Value |\n|:------|:------|\n| **Date** | — |\n| **Status** | 📋 Proposed / ✅ Accepted / ⚠️ Deprecated / 🔄 Superseded |\n| **Phase** | — |\n| **Agent** | — |\n| **Supersedes** | — |\n| **Superseded By** | — |\n\n#### 🔍 Context\n*What problem or question motivated this decision?*\n\n#### ✅ Decision\n*What change are we making?*\n\n#### 📊 Consequences\n*What becomes easier or harder?*\n\n#### 🔗 Governance Link\n*Reference to \`workflow_governance_rules.md\` if applicable.*\n\n---\n\n## ADR-0001: Project Initialization\n\n| Field | Value |\n|:------|:------|\n| **Date** | ${now} |\n| **Status** | ✅ Accepted |\n| **Phase** | Initialization |\n| **Agent** | CLI (create-ai-project) |\n\n#### 🔍 Context\nNew project requires a structured, agent-driven development framework.\n\n#### ✅ Decision\nScaffolded using create-ai-project CLI with AI-OS v1.2.0 framework — 11 phases, 14 agents, 14 workflows.\n\n#### 📊 Consequences\n- All agents and workflows immediately available\n- Phase-based pipeline enforced from day one\n- State tracking operational\n\n---\n`
   );
-  writeFileIfNotExists(path.join(projectPath, '07_state', 'KNOWN_ISSUES.md'), `# KNOWN_ISSUES\n\n-\n`);
-  writeFileIfNotExists(path.join(projectPath, '07_state', 'INCIDENT_LOG.md'), `# INCIDENT_LOG\n\n-\n`);
+  writeFileIfNotExists(path.join(projectPath, '07_state', 'KNOWN_ISSUES.md'), `# 🐛 KNOWN ISSUES\n\n> **Track all known issues across the project lifecycle.** Agents log issues as they discover them.\n\n---\n\n## 📝 Issue Template\n\n> Copy this for each new issue:\n\n| Field | Value |\n|:------|:------|\n| **Issue ID** | ISS-XXX |\n| **Severity** | 🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low |\n| **Phase Discovered** | — |\n| **Agent** | — |\n| **Description** | — |\n| **Impact** | — |\n| **Workaround** | — |\n| **Resolution** | — |\n| **Status** | 🔓 Open / 🔄 In Progress / ✅ Resolved / 🚫 Won't Fix |\n\n---\n\n## 🔓 Active Issues\n\n> *No known issues at this time.* 🎉\n\n---\n\n## ✅ Resolved Issues\n\n> *Nothing resolved yet — project is brand new!*\n\n---\n\n*Agents append issues here automatically during their phases.*\n`);
+  writeFileIfNotExists(path.join(projectPath, '07_state', 'INCIDENT_LOG.md'), `# 🚨 INCIDENT LOG\n\n> **Production incidents and their resolution.** Used post-deployment to track outages, bugs, and recovery.\n\n---\n\n## 📝 Incident Template\n\n> Copy this for each incident:\n\n| Field | Value |\n|:------|:------|\n| **Incident ID** | INC-XXX |\n| **Date** | — |\n| **Severity** | 🔴 P0 (Critical) / 🟠 P1 (High) / 🟡 P2 (Medium) / 🟢 P3 (Low) |\n| **Description** | — |\n| **Root Cause** | — |\n| **Impact** | — |\n| **Resolution** | — |\n| **Time to Detect** | — |\n| **Time to Resolve** | — |\n| **Postmortem** | — |\n| **Prevention** | — |\n\n---\n\n## 📋 Incidents\n\n> *No incidents recorded.* 🎉 *This is a brand-new project!*\n\n---\n\n*This file becomes active after deployment (Phase 11).*\n`);
 
   // Copy bundled 02_Skills (actual full content) into the project.
   if (!fs.existsSync(SKILLS_TEMPLATE_SOURCE)) {
@@ -202,11 +204,14 @@ function main() {
   }
   copyRecursiveNoClobber(SKILLS_TEMPLATE_SOURCE, path.join(projectPath, '02_Skills'));
 
-  // README
-  writeFileIfNotExists(
-    path.join(projectPath, 'README.md'),
-    `# ${projectName}\n\nGenerated by **create-ai-project** (AI-OS).\n\n## Quickstart\n\n\`\`\`bash\ncd \"${projectName}\"\n\`\`\`\n\n## Where things go\n\n- \`02_Skills/\` — standard skills shipped with initializer (ignored by git in this scaffold)\n- \`03_Project_Info/\` — role folders (agents will generate/update docs later)\n- \`06_Documentation/\` — system docs (generated later)\n- \`04_Tasks/\` — task plans + logs\n- \`07_state/\` — decisions + ADR + changelog\n\n## Python default: uv\n\n\`\`\`bash\ncd 05_Project\nuv venv\nuv pip install <pkg>\n\`\`\`\n\nGenerated: ${now}\n`
-  );
+  // Copy CLI package README into the project for reference
+  const cliReadmePath = path.join(__dirname, 'README.md');
+  if (fs.existsSync(cliReadmePath)) {
+    writeFileIfNotExists(
+      path.join(projectPath, 'CLI_PACKAGE_README.md'),
+      fs.readFileSync(cliReadmePath, 'utf8')
+    );
+  }
 
   writeFileIfNotExists(
     path.join(projectPath, '05_Project', 'README.md'),

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@akm1923main/init-project",
-  "version": "1.0.0",
-  "description": "AI-OS project initializer CLI",
+  "version": "1.2.0",
+  "description": "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.",
+  "author": {
+    "name": "akm1923main",
+    "url": "https://github.com/akm1923main"
+  },
   "main": "index.js",
   "type": "commonjs",
   "license": "MIT",
@@ -20,5 +24,13 @@
     "cli",
     "ai",
     "project"
-  ]
-}
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/akm1923main/init-project"
+  },
+  "bugs": {
+    "url": "https://github.com/akm1923main/init-project/issues"
+  },
+  "homepage": "https://github.com/akm1923main/init-project#readme"
+}