Arka Forge

KB-First Research (non-negotiable)

Before any external research (Context7, WebSearch, WebFetch, Firecrawl):

1. Call mcp__obsidian__search_notes on the query first.
2. Cite relevant hits with [[wikilinks]] or explicitly declare a KB gap.
3. Only after (1) and (2) may external tools run.

The Synapse L2.5 layer pre-injects top KB matches on every user prompt; treat them as your default source. External research supplements, it does not replace the vault.

The Forge — ArkaOS Intelligent Planning Engine

> Engine: core/forge/ | Plans stored: ~/.arkaos/plans/ | Obsidian: ArkaOS/Forge/

The Forge analyses any prompt across 5 complexity dimensions, routes to 1-3 explorer subagents for independent plans, runs a critic to synthesize the best plan, and persists an approved ForgePlan before execution. Every plan enforces Constitution rules (branch isolation, spec-driven, QA, Quality Gate, Obsidian output).

Commands

| Command | Description | When to use | |---------|-------------|-------------| | /forge | Forge a new plan | Any task you want planned before executing | | /forge resume | Resume approved plan | After a session break, repo drift, or restart | | /forge status | Show active forge status | Check what plan is currently active | | /forge history | List all past plans | Browse plans saved in ~/.arkaos/plans/ | | /forge show | Show plan detail | Inspect a specific plan by ID | | /forge compare | Compare two plans side-by-side | Evaluate alternative approaches | | /forge patterns | List extracted patterns | See reusable patterns from past plans | | /forge cancel | Cancel active forge | Discard current plan without executing |

Complexity Tiers

| Tier | Score | Explorers | Critic | Companion | Model | |------|-------|-----------|--------|-----------|-------| | Simple (Shallow) | ≤ 30 | 1 (Pragmatic, inline) | Light | None | haiku | | Standard | 31-65 | 2 (Pragmatic + Architectural, parallel) | Full | On request | sonnet | | Complex (Deep) | 66-85 | 3 (+ Contrarian, parallel) | Full | Proactive | opus | | Super | ≥ 86 | 3 + full synthesis | Full (highest judgment) | Proactive | opus |

Five dimensions score 0-100 each: scope, dependencies, ambiguity, risk, novelty. See references/complexity-engine.md for scoring details and tier confirmation prompt.

Subagent Dispatch — Model Routing

When dispatching explorer subagents via the Task tool, include model: parameter. The tier-to-model mapping is:

• simple → model: haiku (fast routing, single explorer)
• standard → model: sonnet (default, 1-2 explorers)
• complex → model: opus (3 explorers + critic synthesis)
• super → model: opus (highest judgment, full synthesis)

Example: for complex tier, use model: opus on every explorer Task call and on the critic synthesis dispatch.

Explorer Lenses

| Lens | Question | Role | |------|----------|------| | Pragmatic | "What is the simplest thing that works?" | Minimum viable, reuse-first, collapse phases | | Architectural | "What is the right way to build this long-term?" | SOLID/DDD/Clean Arch, testability, no tech debt | | Contrarian | "What is everyone missing or assuming wrongly?" | Stress-test assumptions, surface hidden risk |

Full lens prompts and the Critic synthesis prompt live in references/critic-synthesis.md.

Orchestration Overview

Every /forge executes a 10-step flow: (1) context snapshot, (2) Obsidian knowledge check, (3) complexity analysis, (4) tier confirmation gate, (5) launch explorers in parallel, (6) critic synthesis on anonymized outputs, (7) render terminal plan, (8) user decision (Approve / Revise / Companion / Detail / Quit), (9) handoff with repo-drift check, (10) persist to YAML + Obsidian and extract patterns.

Revisions re-run the critic only (not explorers), capped at 5. Secondary commands (resume, status, history, show, compare, patterns, cancel) operate on persisted plans in ~/.arkaos/plans/.

See references/workflows.md for the full step-by-step flows, revision flow, secondary commands, and Constitution enforcement rules.

Plan ID Format

Plan IDs follow the format: forge-YYYYMMDD- (example: forge-20260411-a3f2).

import hashlib, datetime
date = datetime.date.today().strftime("%Y%m%d")
suffix = hashlib.md5(prompt.encode()).hexdigest()[:4]
plan_id = f"forge-{date}-{suffix}"

References

• references/workflows.md — Full 10-step main flow, revision flow, secondary commands, Constitution compliance
• references/complexity-engine.md — Complexity scoring, dimensions, tier thresholds, tier confirmation prompt
• references/critic-synthesis.md — Explorer preamble and 3 lens instructions, Critic subagent synthesis prompt

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andreagroferreira
• Source: andreagroferreira/arka-os
• License: MIT

Install and usage instructions live in the source repository linked above.