singularity-forge/FEATURES.md

# FEATURES

This file is the human-oriented capability map for Singularity Forge.

It is intentionally not the source of truth for schemas or tool parameters. Use it to answer:

- what SF can do today
- which surfaces are first-class versus experimental
- where a capability lives in the system

For exact contracts, use:

- `README.md` for product positioning and user docs
- `src/resources/extensions/sf/workflow-tools.js` for native workflow tool requirements
- `src/resources/extensions/sf/` for planning/state-machine behavior and tool schemas
- `src/resources/extensions/*/extension-manifest.json` for extension inventory
- `packages/pi-ai/src/` for provider and model registry behavior

## Core Product Shape

SF is a coding-agent application built around:

- a milestone → slice → task planning hierarchy
- a DB-backed workflow state machine
- native SF workflow mutations and readers
- extension-based capability loading
- multi-provider model routing
- interactive and autonomous execution modes

The core planning/runtime loop is:

1. discuss / research / align
2. plan milestone
3. plan slice
4. execute task-by-task
5. verify gates
6. summarize and validate
7. reassess roadmap and continue

## Planning And Ceremony Capabilities

### Milestone planning

SF supports milestone plans with:

- milestone title, vision, and slice breakdown
- success criteria and definition of done
- key risks and proof strategy
- verification contract, integration, operational, and UAT sections
- requirement coverage and boundary-map support

### Vision meeting

Milestones can carry a weighted `visionMeeting` that captures:

- `pm`
- `userAdvocate`
- `customerPanel`
- `business`
- `researcher`
- `deliveryLead`
- `partner`
- `combatant`
- `architect`
- `moderator`
- weighted synthesis
- confidence by area
- recommended route: `discussing`, `researching`, or `planning`

This is the top-level roadmap/vision alignment ceremony.

### Slice planning

Slices support:

- goal
- success criteria
- proof level
- integration closure
- observability impact
- ordered task plans with expected files, verification, inputs, outputs

### Adversarial review

Slice planning supports first-class adversarial review with:

- `partner`
- `combatant`
- `architect`

This is treated as required planning structure, not commentary.

### Planning meeting

Slices also support a structured planning meeting with:

- trigger
- `pm`
- `researcher`
- `partner`
- `combatant`
- `architect`
- `moderator`
- recommended route
- confidence summary

This is the narrower execution-readiness ceremony.

### Replanning

When a blocker invalidates a slice plan, SF supports slice replanning with:

- blocker task + blocker description
- what changed
- updated tasks
- removed tasks
- updated slice-level planning fields
- updated adversarial review
- updated planning meeting

Replan state is preserved in DB and re-rendered into plan artifacts.

## Workflow State Machine

The SF workflow engine derives and enforces states including:

- `pre-planning`
- `needs-discussion`
- `planning`
- `evaluating-gates`
- `executing`
- `summarizing`
- `validating-milestone`
- `completing-milestone`
- `replanning-slice`
- `complete`
- `blocked`

Important properties:

- execution readiness is gated by artifact completeness, not just file existence
- meeting/ceremony data participates in readiness
- blocked/dependency-aware progression is built in
- routed-back plans stay in planning instead of pretending to be ready

## Artifact And Persistence Capabilities

SF persists workflow state in multiple synchronized forms:

- SQLite DB (`.sf/sf.db`)
- markdown planning artifacts
- state manifest snapshots
- worktree DB reconciliation state
- workflow events

Planning/ceremony state now survives across:

- DB writes
- markdown rendering
- pure projection rendering
- manifest export / restore
- worktree reconciliation
- state derivation and execution gating
- slice replanning

## Execution Capabilities

SF can execute work in:

- interactive mode
- headless mode
- auto mode
- parallel / multi-worker orchestration

Execution-related features include:

- task-sized dispatch units
- crash recovery and lock-aware state
- timeout supervision
- worktree isolation
- per-unit summaries and milestone completion flow
- roadmap reassessment after completed slices

## MCP And Workflow Tooling

The workflow layer is exposed over MCP, including mutation/read paths for:

- milestone planning
- slice planning
- slice replanning
- task completion
- slice completion
- milestone validation
- milestone completion
- roadmap reassessment
- gate results
- summary save/read flows

This makes SF usable from external clients without relying on slash-command prompt tricks.

## Search And Research Capabilities

SF has dedicated web/research support via onboarding, auth storage, and extension flows.

Currently supported first-class web-search providers include:

- `brave`
- `tavily`
- `serper`
- `exa`

Other search/research surfaces include:

- Ollama native web search / fetch integration
- Google search extension
- Context7 extension for library/documentation retrieval
- Jina-backed content extraction paths where configured

The search stack is available to automatic workflows, not only slash commands.

## Subagents And Background Work

SF includes subagent capabilities via the `subagent` extension, including:

- delegated agent runs
- background subagent jobs
- await/join behavior
- cancellation
- workflow-driven use rather than only interactive commands

This is useful for automatic coding flows and wave-based task execution.

## Extension Inventory

Bundled extension families currently include:

- `sf` — workflow engine, planning/state/artifacts
- `search-the-web`
- `subagent`
- `async-jobs`
- `bg-shell`
- `browser-tools`
- `context7`
- `google-search`
- `ollama`
- `remote-questions`
- `slash-commands`
- `mac-tools`
- `ttsr`
- `universal-config`
- `voice`

These are not all equal in product importance, but they are real shipped extension surfaces.

## Model And Provider Capabilities

SF supports multi-provider model routing across built-in and custom providers.

Notable supported/known providers in the current runtime and registry surface include:

- `anthropic`
- `anthropic-vertex`
- `openai`
- `azure-openai-responses`
- `openai-codex`
- `google`
- `google-gemini-cli`
- `google-vertex`
- `mistral`
- `amazon-bedrock`
- `ollama`
- `ollama-cloud`
- `openrouter`
- `groq`
- `xai`
- `github-copilot`
- `zai`
- `minimax`
- `minimax-cn`
- `kimi-coding`
- `xiaomi`
- `custom-openai`

Recent/custom provider support in this tree also includes:

- `zai` / GLM-family routing
- `xiaomi` / MiMo Anthropic-compatible endpoint
- `kimi-coding` / dedicated coding endpoint
- `minimax` Anthropic-compatible support

## Onboarding And Auth

Onboarding currently supports:

- LLM provider selection
- OAuth or API-key based provider setup where applicable
- local Ollama detection
- web-search provider setup
- remote questions setup
- tool-key collection for selected extensions

This is a real product capability, not just a doc path.

## Recovery, Reliability, And Operational Features

SF includes real operational hardening around:

- manifest bootstrapping and restore
- worktree/DB reconciliation
- cache invalidation around plan parsing
- atomic writes and TOCTOU protection
- gate-aware progression
- idle/timeout handling
- scoped recovery for auto mode

## UI And Interaction Surfaces

SF is not only a CLI. The repo also carries:

- TUI support
- web interface support
- VS Code extension support
- MCP server support

So the product surface is broader than “terminal prompt framework.”

## What This File Does Not Try To Be

This file does not list:

- every MCP tool parameter
- every extension command
- every model ID
- every preference flag
- every internal DB column

Those should stay close to code or generated inventories.

## Generated Inventory

The section below is generated from source declarations so this overview can stay concise while exact inventories remain refreshable.

<!-- GENERATED_FEATURE_INVENTORY_START -->

### SF Native Tools

Generated from `src/resources/extensions/sf/extension-manifest.json`.

- `sf_autonomous_checkpoint`
- `sf_complete_milestone`
- `sf_decision_save`
- `sf_exec`
- `sf_exec_search`
- `sf_graph`
- `sf_journal_query`
- `sf_log_judgment`
- `sf_milestone_generate_id`
- `sf_milestone_status`
- `sf_plan_milestone`
- `sf_plan_slice`
- `sf_plan_task`
- `sf_product_audit`
- `sf_reassess_roadmap`
- `sf_replan_slice`
- `sf_requirement_save`
- `sf_requirement_update`
- `sf_resume`
- `sf_save_gate_result`
- `sf_self_feedback_resolve`
- `sf_self_report`
- `sf_skip_slice`
- `sf_slice_complete`
- `sf_summary_save`
- `sf_task_complete`
- `sf_validate_milestone`

### Bundled Extensions

Generated from `src/resources/extensions/*/extension-manifest.json`.

- `async-jobs` — [extension-manifest.json](src/resources/extensions/async-jobs/extension-manifest.json)
- `aws-auth` — [extension-manifest.json](src/resources/extensions/aws-auth/extension-manifest.json)
- `bg-shell` — [extension-manifest.json](src/resources/extensions/bg-shell/extension-manifest.json)
- `browser-tools` — [extension-manifest.json](src/resources/extensions/browser-tools/extension-manifest.json)
- `claude-code-cli` — [extension-manifest.json](src/resources/extensions/claude-code-cli/extension-manifest.json)
- `context7` — [extension-manifest.json](src/resources/extensions/context7/extension-manifest.json)
- `github-sync` — [extension-manifest.json](src/resources/extensions/github-sync/extension-manifest.json)
- `google-search` — [extension-manifest.json](src/resources/extensions/google-search/extension-manifest.json)
- `guardrails` — [extension-manifest.json](src/resources/extensions/guardrails/extension-manifest.json)
- `mac-tools` — [extension-manifest.json](src/resources/extensions/mac-tools/extension-manifest.json)
- `mcp-client` — [extension-manifest.json](src/resources/extensions/mcp-client/extension-manifest.json)
- `ollama` — [extension-manifest.json](src/resources/extensions/ollama/extension-manifest.json)
- `remote-questions` — [extension-manifest.json](src/resources/extensions/remote-questions/extension-manifest.json)
- `search-the-web` — [extension-manifest.json](src/resources/extensions/search-the-web/extension-manifest.json)
- `sf` — [extension-manifest.json](src/resources/extensions/sf/extension-manifest.json)
- `sf-inturn-guard` — [extension-manifest.json](src/resources/extensions/sf-inturn-guard/extension-manifest.json)
- `sf-notify` — [extension-manifest.json](src/resources/extensions/sf-notify/extension-manifest.json)
- `sf-permissions` — [extension-manifest.json](src/resources/extensions/sf-permissions/extension-manifest.json)
- `sf-tui` — [extension-manifest.json](src/resources/extensions/sf-tui/extension-manifest.json)
- `sf-usage-bar` — [extension-manifest.json](src/resources/extensions/sf-usage-bar/extension-manifest.json)
- `slash-commands` — [extension-manifest.json](src/resources/extensions/slash-commands/extension-manifest.json)
- `subagent` — [extension-manifest.json](src/resources/extensions/subagent/extension-manifest.json)
- `ttsr` — [extension-manifest.json](src/resources/extensions/ttsr/extension-manifest.json)
- `universal-config` — [extension-manifest.json](src/resources/extensions/universal-config/extension-manifest.json)
- `vectordrive` — [extension-manifest.json](src/resources/extensions/vectordrive/extension-manifest.json)
- `voice` — [extension-manifest.json](src/resources/extensions/voice/extension-manifest.json)

### Search Providers

Generated from the `search-the-web` extension provider declarations.

- `brave`
- `exa`
- `ollama`
- `serper`
- `tavily`

### Known Model Providers

Generated from `packages/pi-ai/src/types.ts` (`KnownProvider`).

- `alibaba-coding-plan`
- `alibaba-dashscope`
- `amazon-bedrock`
- `anthropic`
- `anthropic-vertex`
- `azure-openai-responses`
- `cerebras`
- `github-copilot`
- `google`
- `google-gemini-cli`
- `google-vertex`
- `groq`
- `huggingface`
- `kimi-coding`
- `longcat`
- `minimax`
- `minimax-cn`
- `mistral`
- `ollama`
- `ollama-cloud`
- `openai`
- `openai-codex`
- `opencode`
- `opencode-go`
- `openrouter`
- `vercel-ai-gateway`
- `xai`
- `xiaomi`
- `xiaomi-token-plan-ams`
- `xiaomi-token-plan-cn`
- `xiaomi-token-plan-sgp`
- `zai`

<!-- GENERATED_FEATURE_INVENTORY_END -->