{
  "markdown": "# ForgeStack\n\n**Autonomous full-stack application factory for AI coding assistants.**\n\nClone this repo into your workspace and your AI assistant — Copilot, Claude, Cursor, Codex, or any AGENTS.md-compatible runtime — transforms into a Virtual Technical Lead that builds complete, tested, production-ready applications from requirements to deployed code.\n\n---\n\n## What ForgeStack Does\n\n1. **INTAKE** — Interviews you to capture features, scale, constraints, and preferences\n2. **SPEC** — Writes a behavioral contract (F-contracts + M-contracts) for every feature before any code is written\n3. **ARCHITECTURE** — Recommends a technology stack and generates flowchart, component, and sequence diagrams\n4. **PLANNING** — Decomposes the project into a weighted agile backlog (Fibonacci story points, spec refs, one test per task)\n5. **IMPLEMENTATION** — Writes complete production code for each task, in dependency order, with an auto-fix loop on test failures\n6. **DELIVERY** — Produces a runnable, tested, fully-scaffolded application in `output/<project-id>/`\n\nAll decisions are persisted to `.forgestack/sessions/` so any interruption is fully recoverable.\n\n---\n\n## ⚡ Token Efficiency Mode (Caveman + Model-Mixing)\n\n**Reduce token cost by 70-83% per project.**\n\nForgeStack includes comprehensive token optimizations:\n\n### 1. **Caveman Prompting** (70% token reduction)\nUltra-compressed, minimal instructions across all phases:\n- AGENTS.md: 3,000 words → 800 words\n- CLAUDE.md: 800 words → 400 words  \n- SYSTEM_PROMPT.md: 1,500 words → 600 words\n\n✅ **Fully backward compatible** — existing projects unaffected.\n\n### 2. **Lazy-Load Context** (80% context reduction)\nSmart context slicing instead of full session JSON:\n```bash\n# Load only what you need:\nsync_context.py --id PROJECT_ID --slice task_only      # Current task (~400 bytes)\nsync_context.py --id PROJECT_ID --slice context_only   # Status only (~300 bytes)\nsync_context.py --id PROJECT_ID --slice backlog_pending # Next tasks (~1KB)\nsync_context.py --id PROJECT_ID                         # Full context (2KB, default)\n```\n\n### 3. **Model-Mixing** (40% cost reduction)\nUse cheapest model per phase:\n- **INTAKE** → Haiku (interview synthesis)\n- **SPEC** → Haiku (formula contracts)\n- **ARCHITECTURE** → Sonnet (complex reasoning + diagrams)\n- **PLANNING** → Haiku (mechanical decomposition)\n- **IMPLEMENTATION** → Flash (high-volume code generation)\n- **QA** → Haiku (test validation)\n\nSee `MODEL_MAP.md` for provider-specific model IDs + detailed cost breakdown.\n\n### 4. **Micro-Task Decomposition** (10% savings)\nSplit large tasks (>3 points) into atomic subtasks (1-3 points):\n```bash\npython .agents/skills/forgestack/scripts/micro_plan.py --id PROJECT_ID\n```\nEach subtask fits in Haiku context, avoiding expensive Sonnet calls.\n\n### Cost Comparison\n\n| Approach | Tokens per Build | Cost per Build | Time |\n|----------|------------------|---|---|\n| Default (all Sonnet) | ~190k | $3.30 | ~60s |\n| Caveman only | ~133k | $2.30 | ~50s |\n| Caveman + Model-mixing | ~56k | $0.55 | ~45s |\n| Caveman + All optimizations | ~48k | $0.48 | ~40s |\n\n**Savings: 70-83% per project.**\n\n### Quick Start with Optimizations\n\n```bash\n# New project\npython .agents/skills/forgestack/scripts/init_project.py --name \"MyApp\" --description \"...\"\n\n# After PLANNING phase, split large tasks\npython .agents/skills/forgestack/scripts/micro_plan.py --id PROJECT_ID\n\n# During IMPLEMENTATION, use lazy-load context\npython .agents/skills/forgestack/scripts/sync_context.py --id PROJECT_ID --slice task_only\n\n# See MODEL_MAP.md for model-mixing hints\n```\n\n### Learn More\n- `MODEL_MAP.md` — Model selection strategy + cost analysis\n- `CAVEMAN_PROMPTS.md` — Ultra-compressed prompt templates\n- `OPTIMIZATION_PLAN.md` — Design rationale\n- `IMPLEMENTATION_SUMMARY.md` — Detailed changelog\n\n---\n\n### 1. Clone Into Your Workspace\n\n```bash\ngit clone https://github.com/prematzerosoft/forgestack .forgestack-agent\n```\n\nOr add as a git submodule:\n```bash\ngit submodule add https://github.com/prematzerosoft/forgestack .forgestack-agent\n```\n\n### 2. No Installation Required\n\nThe session scripts are plain Python 3.8+ with zero external dependencies. No `pip install`, no venv needed.\n\n### 3. Invoke Your AI Assistant\n\n| Runtime | How to Invoke |\n|---------|--------------|\n| **VS Code Copilot** | Open Chat → type `@ForgeStack build me a task manager` |\n| **VS Code Copilot (prompt)** | Open Chat → `/new-project` |\n| **Claude Code** | Start a session — `CLAUDE.md` loads automatically |\n| **Cursor** | Open Chat — `.cursor/rules/forgestack.mdc` loads automatically |\n| **Windsurf** | Open Cascade — `.windsurfrules` loads automatically |\n| **JetBrains Junie** | Open Junie — `.junie/guidelines.md` loads automatically |\n| **Amazon Q Developer** | Open Q Chat — `.amazonq/rules/forgestack.md` loads automatically |\n| **OpenAI Codex** | `AGENTS.md` at repo root is read automatically |\n| **Gemini CLI** | `AGENTS.md` at repo root is read automatically |\n| **Aider** | `AGENTS.md` at repo root is read automatically |\n| **Devin** | `AGENTS.md` at repo root is read automatically |\n| **ChatGPT / Gemini web / Claude.ai** | Copy `SYSTEM_PROMPT.md` → paste as first message |\n| **Any other chat UI** | Copy `SYSTEM_PROMPT.md` → paste as first message |\n| **Any AGENTS.md runtime** | `AGENTS.md` at repo root is read automatically |\n\n---\n\n## Directory Structure\n\n```\nforgestack/\n│\n├── AGENTS.md                          # Universal entry point (all AGENTS.md runtimes)\n├── CLAUDE.md                          # Claude Code adapter\n├── SYSTEM_PROMPT.md                   # Copy-paste starter for any chat UI (ChatGPT, Gemini web, etc.)\n├── LICENSE                            # MIT\n│\n├── .github/\n│   ├── agents/\n│   │   ├── forgestack.agent.md        # VS Code Copilot — main orchestrator (@ForgeStack)\n│   │   ├── intake.agent.md            # Sub-agent: requirements gathering\n│   │   ├── spec.agent.md              # Sub-agent: behavioral spec (F/M contracts)\n│   │   ├── architect.agent.md         # Sub-agent: tech stack + diagrams\n│   │   ├── planner.agent.md           # Sub-agent: backlog decomposition\n│   │   ├── implementer.agent.md       # Sub-agent: code generation\n│   │   └── qa.agent.md                # Sub-agent: test execution + auto-fix\n│   └── prompts/\n│       ├── new-project.prompt.md      # /new-project slash command\n│       ├── resume-project.prompt.md   # /resume-project slash command\n│       └── project-status.prompt.md  # /project-status slash command\n│\n├── .agents/\n│   └── skills/\n│       └── forgestack/\n│           ├── SKILL.md               # Provider-neutral skill definition\n│           ├── scripts/               # Session management (Python, no deps)\n│           │   ├── list_projects.py\n│           │   ├── init_project.py\n│           │   ├── load_session.py\n│           │   ├── save_session.py\n│           │   ├── sync_context.py\n│           │   ├── validate_phase.py\n│           │   └── write_phase_doc.py\n│           └── references/\n│               ├── state-schema.md    # Full session JSON schema\n│               └── workflow.md        # Detailed SDLC procedure\n│\n├── .cursor/\n│   └── rules/\n│       └── forgestack.mdc             # Cursor IDE adapter\n│\n├── .windsurfrules                     # Windsurf (Cascade) adapter\n│\n├── .junie/\n│   └── guidelines.md                  # JetBrains Junie adapter\n│\n├── .amazonq/\n│   └── rules/\n│       └── forgestack.md              # Amazon Q Developer adapter\n│\n└── .forgestack/                       # Runtime data (gitignored)\n    └── sessions/\n        └── <project-id>.json          # Persistent session state per project\n```\n\n---\n\n## Session Awareness\n\nForgeStack never loses context. Every phase saves state to `.forgestack/sessions/<id>.json`. To recover from any interruption:\n\n```bash\npython .agents/skills/forgestack/scripts/list_projects.py\npython .agents/skills/forgestack/scripts/sync_context.py --id PROJECT_ID\n```\n\nThen tell your AI assistant: `resume project PROJECT_ID`.\n\n---\n\n## Session Scripts\n\nAll scripts run from the repo root. Python 3.8+, zero dependencies.\n\n```bash\n# List all projects\npython .agents/skills/forgestack/scripts/list_projects.py\n\n# Start a new project (prints project ID)\npython .agents/skills/forgestack/scripts/init_project.py --name \"MyApp\" --description \"...\"\n\n# Load full session JSON\npython .agents/skills/forgestack/scripts/load_session.py --id PROJECT_ID\n\n# Update a session field\npython .agents/skills/forgestack/scripts/save_session.py --id PROJECT_ID --field status --data '\"planning\"'\n\n# Get compact awareness summary (inject at start of each phase)\npython .agents/skills/forgestack/scripts/sync_context.py --id PROJECT_ID\n```\n\n---\n\n## Requirements\n\n- Python 3.8+ (for session scripts)\n- An AI assistant with file-system access (Copilot, Claude Code, Cursor, Codex, etc.)\n- No other dependencies\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## Contributing\n\nIssues and PRs welcome. See [AGENTS.md](AGENTS.md) for the full workflow specification that all agents follow.\n\nThis repository is being bootstrapped as an open-source MIT project for the Forgestack orchestrator.",
  "bytes": 9125,
  "sha": "716068dcd9c5f6a27f93953fe45016225adf82cf3a54b2f2dc0cba3f6e4fa4cf",
  "repo_slug": "prematzerosoft/forgestack",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_prematzerosoft_forgestack_forgestack_1564986b/readme"
}