↻
Durable re-entry
The current mode, stage, tasks and next action are stored in .sia/. A fresh chat, a compacted context or a different host picks up exactly where the last one stopped.
A control plane for agentic work
SIA does not replace your model or IDE. It gives the host a shared, inspectable contract and saves workflow state under .sia/.
◇
Evidence-gated stages
Specs, instructions, skills, plans and integration records must exist on disk before the workflow advances. A claim in conversation is never evidence.
∞
Learns from your corrections
Say it once (“keep answers short”, “never touch infra/ without asking”) and it becomes a standing rule. Rules load into every session and every subagent, and ones a machine can check, like a banned word, are checked on every file write and reply.
✎
Skills for your project
SIA reads your spec and writes one skill per capability it asks for, where Claude Code and Codex find them. Each skill quotes the requirement it serves; SIA refuses one it cannot trace.
⋈
Cheaper subagents, independent review
Tasks own exact files and route to cheap, current or strong models by risk, under hard budgets. Every task is reviewed by a different agent before integration.
⇄
Works with your plugins
SIA detects Superpowers and BMAD, vendored or installed as plugins. Superpowers writes the spec and plan, SIA dispatches, and subagents use its TDD and verification skills.
Three runtime modes
Runtime mode is independent of the intake approach you choose for an existing project.
Advisory
SIA owns feedback capture, standing rules, preflight, and convergence. Use this when BMAD, Superpowers, or your team already owns planning and execution.
sia init --mode advisory
Planning
SIA owns intake, specification, project instructions, generated skills, and plan. A different framework or human team can execute.
sia init --mode planning
Orchestrator
SIA owns the full evidence pipeline and coordinates host-native implementers and reviewers. It still does not impersonate a vendor agent API.
sia init --mode orchestrator
Install, initialize, resume
Install the plugin in your host
No pip install is needed. The plugin bundles SIA and runs it as an MCP server your host starts for you; Python 3.10 or newer is the only prerequisite.
Claude Code — verified
/plugin marketplace add GunjanGrunge/SIA_package /plugin install sia@sia
Codex — verified
codex plugin marketplace add GunjanGrunge/SIA_package codex plugin add sia@sia # Older Codex (e.g. 0.121) has no "codex plugin" command: codex marketplace add GunjanGrunge/SIA_package # then install sia from /plugins inside Codex
Gemini CLI — not yet tested
gemini extensions install https://github.com/GunjanGrunge/SIA_package
Kiro and Antigravity are packaged but not yet tested. Then say “set up SIA on this project”: the sia-start skill walks the project from intake to execution, so the remaining steps below are handled for you.
Codex asks before SIA writes. Read-only tools run without a prompt; tools that change .sia/ ask for approval. In a non-interactive codex exec run, allow SIA’s own tools with -c 'plugins."sia@sia".mcp_servers.sia.default_tools_approval_mode="approve"'.
Or: the CLI on its own
Only needed to script SIA outside an agent host, or for the standalone backend’s orchestrate run --approve-commands, which is deliberately not exposed to agents.
PowerShell / terminal
python -m pip install "git+https://github.com/GunjanGrunge/SIA_package"
Open the target project
Run SIA from the actual repository root. Choose one runtime mode.
cd path/to/your-project sia init --mode orchestrator sia doctor
Install one host launcher
Claude, Codex, Kiro, and Antigravity have collision-safe, opt-in adapters. Gemini CLI uses the manual host-neutral flow documented below.
sia adapter install --host claude # or: codex | kiro | antigravity
Configure routing and budget
Generate the template, then set exact provider IDs for cheap, current, and strong models, configured prices, token/USD ceilings, and concurrency.
sia orchestrate example > orchestration.json sia orchestrate configure --file orchestration.json
Ask the host to resume SIA
The JSON packet is the durable source of workflow position.
sia next --json
Walk the stages to execution
Read this before reporting a bug. init leaves the project at intake. In orchestrator mode, task prepare and orchestrate plan are illegal until the project reaches execution — five evidence-gated advances away. Configuring routing before then succeeds and then refuses to dispatch, which reads like a failure but is the gate doing its job.
intake → spec → project-instructions → skills → plan → execution sia next --json # what this stage requires sia advance --evidence <path> # once that artifact exists
A stage transition needs an artifact on disk, never a claim in conversation. The Claude Code plugin’s sia-start skill walks this for you. Use advisory mode if you want the feedback loop without the gates.
Use the cheapest model that can safely do the job
SIA does not hard-code vendor aliases or guess the model selected in your IDE. You configure exact IDs once; every plan persists the tier, model, reason, reservation, and fallback policy.
Bounded workers
Low-risk/simple implementation, exploration, routine tests, documentation, triage, and high-volume supporting work.
Claude Code: haiku
Selected capable model
Normal implementation, coordination, and independent review. Set this to the exact model you selected or approved for the project.
Claude Code: sonnet
Risk and escalation
Complex architecture, security/high-risk implementation, high-risk review, and configured escalation after a cheaper attempt fails.
Claude Code: opus
One router, two backends
# The active assistant spawns native subagents sia orchestrate plan --backend native-host --host claude # SIA launches approved provider CLI workers sia orchestrate plan --backend standalone --host provider-cli sia orchestrate run --approve-commands
Budget and telemetry truth
Plan estimates reserve tokens and USD atomically before dispatch. Warnings trigger at the configured fraction; hard ceilings reject plans and stop new standalone review scheduling. Receipts label usage as actual, calculated, estimated, or unknown. Savings require an explicit baseline.
sia orchestrate status
The routing reaches the spawn. The controller passes each task’s model to the host’s subagent tool, so a cheap task really runs on the cheap model. Verified in Claude Code: the implementer ran on Haiku and the reviewer on Sonnet. On very small tasks the main session’s own planning outweighs the saving; it grows with the amount of work delegated.
Security boundary: standalone command arrays use
shell=False, whole-argument placeholders, minimal environment allowlists, no stdin, bounded logs, and timeouts. They still run with your OS user permissions and are not a filesystem/network sandbox.Use SIA with your preferred host
The logos below are loaded from each tool's official domain. SIA and its authors are not affiliated with or endorsed by these vendors.
Prefer the plugin. The plugin install gives you SIA’s tools, hooks, skills and agents with no CLI setup. The per-host adapters below are the older CLI-based route, kept for hosts or setups where the plugin is not available.
Claude CodeProject skill · explicit
/sia- Initialize SIA in the project root.
- Install the manual-only Claude skill.
- In Claude Code, invoke
/sia. The skill runs the persisted packet and leaves other skills available.
sia init --mode orchestrator sia adapter install --host claude sia next --json
Installed path: .claude/skills/sia/SKILL.md
OpenAI CodexRepo skill · AGENTS.md compatible
- Keep the repository's existing
AGENTS.md; SIA does not replace it. - Install the repo-local SIA skill.
- Ask Codex to use SIA, then follow
sia next --json. Record native run IDs when dispatching.
sia init --mode orchestrator sia adapter install --host codex sia next --json
Installed path: .agents/skills/sia/SKILL.md
Gemini CLINative Agent Skill · model-routed subagents
First-class adapter: SIA installs a project Agent Skill; Gemini custom agents provide exact model, tools, max-turn, and timeout controls.
- Initialize and configure SIA's cheap/current/strong model IDs.
- Install the Gemini skill adapter.
- Invoke SIA explicitly. The main Gemini agent consumes the immutable plan and delegates to `.gemini/agents/*.md` specialists; subagents cannot recursively spawn more subagents.
sia init --mode orchestrator sia adapter install --host gemini sia orchestrate configure --file orchestration.json sia orchestrate plan --backend native-host --host gemini
Installed path: .gemini/skills/sia/SKILL.md
Use each routed operation's exact model in the custom agent frontmatter. Record actual usage when exposed; otherwise retain SIA's estimate.
Official Gemini CLI subagents/model configuration ↗ · Agent Skills ↗
Google AntigravityCustom workflow · native agents
- Initialize SIA in the Antigravity workspace root.
- Install the workflow adapter.
- Invoke
/siafrom Agent Manager. Use native agents for prepared implementation/review tasks.
sia init --mode orchestrator sia adapter install --host antigravity sia next --json
Installed path: .agents/workflows/sia.md
Official parallel Antigravity agents codelab ↗ · Workflows ↗
KiroManual steering · native subagents
- Install the manual steering adapter.
- Invoke the SIA steering command explicitly.
- In orchestrator mode, delegate prepared tasks to Kiro subagents and record each implementer/reviewer identity.
sia init --mode orchestrator sia adapter install --host kiro sia next --json
Installed path: .kiro/steering/sia.md
Any other coding assistantStandalone prompt packet
If a host can run commands and read files, it can use SIA without an adapter:
sia init --mode planning sia next --json
Give the JSON result to the host and ask it to follow the current stage. Use advisory/planning mode when the host cannot provide native subagents or independent run identities.
The persistent SIA pipeline
Approval gates wrap every stage. The current stage is persisted; the assistant does not infer it from conversation memory.
01IntakeGoal, evidence, boundaries
02SpecApproved architecture
03InstructionsProject rules
04SkillsRequirement-backed pack
05PlanFiles and interfaces
06ExecutionDispatch and review
07FeedbackRules and convergence
Advancing evidence-gated stages
Ask what comes next
sia status sia next --json
Every host follows the same packet, so changing tools does not reset the process.
Attach the artifact
sia advance --evidence docs/specs/export.md
Specification, instructions, skills, and plan stages require project-local evidence paths.
Skills written from your project’s requirements
SIA does not hand every project the same pack. It reads the recorded intake, spec, plan and agent instructions, and writes one skill per capability they call for.
Grounded, not guessed
Every skill quotes, word for word, the requirement it serves. SIA checks the quote is in a requirement source and refuses the skill otherwise. Dependencies only shape how a skill works, never whether it exists.
Used everywhere
Skills are installed in .claude/skills/ and .agents/skills/, so the main agent, every subagent and collaborating plugins can load them. Subagents are told to load the relevant ones first.
Kept current, kept safe
Rules learned from your corrections are written into matching skills automatically. SIA never overwrites a skill it did not write, and stops updating one you edited.
How the agent does it
sia_skill_context # requirements, deps, existing skills sia_skill_write # one call per skill, with citations sia advance --evidence sdd/skill-manifest.md
Verified in Claude Code
A churn-model spec asking for data profiling, per-epoch loss logging and an F1 ship gate, with hyperparameters fixed, produced exactly three skills: profiling, training loop and evaluation. No tuning skill was written, even though optuna was installed.
Prepare → route → run → receipt → integrate
SIA routes all operations before execution, launches real standalone workers or instructs the native host to spawn them, then unlocks independent reviewers only after implementation receipts complete.
1 · Prepare ownership and routing metadata
sia task prepare \ --task backend \ --brief sdd/backend-brief.md \ --files src/api.py \ --risk high \ --complexity complex \ --estimated-tokens 40000 sia task prepare \ --task docs \ --brief sdd/docs-brief.md \ --files docs/guide.md \ --risk low \ --complexity simple \ --estimated-tokens 8000
2 · Create the immutable routed plan
# Active coding assistant spawns native agents sia orchestrate plan --backend native-host --host kiro # Or SIA launches approved provider CLI processes sia orchestrate plan --backend standalone --host provider-cli sia orchestrate run --approve-commands
3 · Native hosts submit one receipt per operation
sia orchestrate receipt --file backend-implement-receipt.json sia orchestrate status # Routed reviewer operations become ready automatically.
4 · Bind all receipts to integration
sia integration --evidence sdd/integration.md sia advance
What SIA rejects: over-budget plans, overlapping paths, project-root escape, unknown placeholders, silent model mismatch, duplicate/falsified plan hashes, the same implementer/reviewer identity, empty reports, unfinished orchestration, and stale integration.
Turn corrections into standing rules
You do not run these commands yourself. When you correct the agent or state a preference, it records a rule with your words as evidence, one rule per preference.
Recall
Every active rule loads at the start of each session and after /compact. The agent does not have to remember to ask.
Enforcement
Rules a machine can check, such as a banned word or character, are checked on every file the agent writes and every reply. Violations go back to the agent to fix.
Every subagent
Each subagent receives the rules when it starts, whoever spawned it, so a worker that never saw your conversation still avoids the mistake.
Under the hood
Record outcomes
sia record \ --outcome pass \ --signal review \ --context "Approved without correction" \ --severity low sia capture \ --signal review-finding \ --context "Controller touched an owned file" \ --severity high \ --error-class ownership-breach
Learn, add and apply rules
sia rule learn \ --text "Keep replies under five bullets" \ --user-quote "your answers are too long" sia rule add \ --text "Never edit dispatched task files" \ --scope "src/*.py" \ --severity high \ --error-class ownership-breach \ --source-event <event-id> sia preflight --scope src/api.py sia convergence
Medium/high matching rules require acknowledgment. Rules keep source event, evidence, severity, error class, scope, introduction date, and active/retired status.
Share ownership instead of replacing tools
SIA's default framework policy is bridge. Existing framework files remain off limits.
With Superpowers installed
Superpowers’ brainstorming and writing-plans skills author the spec and plan; SIA still gates on them. SIA is the only dispatcher, so work is never done twice, and SIA’s implementer and reviewer subagents are told to use Superpowers’ test-driven development, debugging and verification skills. Project skills point to Superpowers instead of repeating it.
Let BMAD own planning
sia owner --stage plan --to bmad sia next --json
The packet tells the host to obtain BMAD's artifact before SIA advances.
Use only the learning loop
sia init --mode advisory sia capture ... sia preflight --scope src/auth.py sia convergence
Other frameworks own the delivery process while SIA maintains project feedback.
CLI command map
| Command | Purpose | Typical time |
|---|---|---|
sia init --mode … | Create durable project state in advisory, planning, or orchestrator mode. | Once per project/run |
sia status | Show mode, current stage/owner, tasks, and integration state. | Any time |
sia next --json | Produce the host-neutral next-action packet. | Every SIA turn/new session |
sia guide | Print the complete installed workflow policy. | Installed-only use |
sia doctor | Check initialization and complete policy availability. | After install/update |
sia owner | Assign one stage to SIA or another framework. | When bridging tools |
sia advance | Validate evidence and complete the current stage. | Stage boundary |
sia adapter install/remove | Manage collision-safe host launchers (older route; the plugin replaces this). | Host setup |
sia task prepare | Define task brief, exclusive paths, risk, complexity, and estimate. | Before planning |
sia orchestrate configure | Validate/store exact models, prices, budgets, routing, concurrency, and workers. | Project/run setup |
sia orchestrate plan | Route operations, reserve budget, and persist immutable plan/hash. | Before workers |
sia orchestrate run | Launch approved standalone workers concurrently with shell disabled. | Standalone backend |
sia orchestrate receipt | Ingest native-host operation identity, model, report, and telemetry. | After each native worker |
sia orchestrate status | Show operation counts, token/USD ledger, and telemetry quality. | During execution |
sia task dispatch/finish | Legacy/manual evidence flow retained for backward compatibility. | Non-managed tasks |
sia integration | Bind combined evidence to the complete reviewed task set. | End of execution |
sia record / capture | Persist PASS or DEVIATION outcomes. | After proposals/reviews |
sia rule learn | Turn a user correction into a standing rule in one step. | Whenever the user corrects |
sia rule add/list/retire | Manage provenance-bearing standing rules. | After approved learning |
sia skill context | Requirement sources, dependencies, existing skills and rules. | Skills stage |
sia skill write/list/retire | Write, list or remove requirement-backed project skills. | Skills stage, after spec changes |
sia preflight | Load matching active rules before related work. | Before proposals/changes |
sia convergence | Compute overall and per-error-class deviation rates. | Milestones/reviews |
What is stored where
.sia/
├── config.json # models, routing, budget, owners
├── state.json # stage, operations, telemetry
├── events.jsonl # append-only outcomes
├── rules.json # active and retired rules
├── skills.json # generated project skills
├── project.lock # atomic reservations/transitions
└── runs/<run-id>/
├── dispatch-plan.json
├── integration.md
└── tasks/<task-id>/
├── attempts/
└── receipts/
.claude/skills/<name>/SKILL.md # project skills (Claude Code)
.agents/skills/<name>/SKILL.md # project skills (Codex)
sdd/skill-manifest.md # requirement behind each skill
Commit intentionally
SIA runtime evidence can contain user corrections, paths, and review context. Review it for secrets before committing. Generated project artifacts—specs, plans, skills, and selected sdd/ mirrors—are normal project history.
Trust boundary
SIA checks ordering, path ownership, evidence presence, reviewer separation, and state consistency. It cannot cryptographically prove a vendor agent ran; native IDs are supplied by the host/controller.
VS Code-compatible extension
An extension for VS Code-compatible IDEs lives under extension/. It is not shipped as a prebuilt VSIX in the repository — build it from source. Install sia-package first: the extension delegates initialization and status to the Python runtime and does not maintain a second state machine.
python -m pip install "git+https://github.com/GunjanGrunge/SIA_package" cd extension && npm install && npx vsce package # In VS Code: Extensions → … → Install from VSIX # Select the .vsix produced above
Common questions
SIA says the project is not initialized
Run
sia init --mode advisory|planning|orchestrator from the project root, then sia doctor.The host did not invoke SIA automatically
This is intentional: SIA does not take over unrelated prompts. Say “set up SIA on this project” or “where is SIA on this project?”, or use
/sia:sia-start in Claude Code. Rules still load automatically in every session.How does SIA choose cheap versus current/strong?
The approved orchestration config maps low/simple, normal, high/complex, and review roles to explicit model tiers. Every decision and exact provider model ID is persisted in the immutable plan.
Can SIA spawn agents by itself?
Yes, in standalone mode it launches explicitly approved provider CLI command arrays concurrently with
shell=False. In native-host mode, the active coding assistant uses its own subagent tool from SIA's plan. Native IDs remain caller-attested.SIA blocks a second parallel task
Its owned path intersects an active task. Sequence the work or give a later integration task exclusive ownership of the shared file.
Preflight exits with code 2
A matching medium/high standing rule needs acknowledgment. Review the rule and use
--acknowledge <rule-id> only after approval.I use BMAD or Superpowers
Keep them. SIA detects both, lets Superpowers author the spec and plan, tells subagents to use its practice skills, and never edits either framework’s files. For full hand-off use advisory mode, or assign single stages with
sia owner.Why didn’t SIA write a skill for something my project uses?
Skills come from requirements, not dependencies. If the spec, plan or agent instructions do not ask for a capability, SIA will not write a skill for it. Add the requirement to the spec, and the next skills refresh can cite it.
Repository resources
USAGE.md
Long-form project, host, brownfield, and implementation guidance.
Host contract
Modes, re-entry protocol, adapter paths, and native-agent boundary.
Validation
Dogfood scenarios and runtime safety boundaries.
Source code
Runtime, adapters, guides, extension, issues, and release history.
Changelog
What changed in each release, and how it was verified.
Report an issue
Questions, bugs, integration gaps, and host adapter requests.