pi-ouroboros

English | 简体中文

A prompt-first autonomous coding workflow for pi: project understanding + recoverable work loop + thin runtime primitives.

pi-ouroboros is not a hard-coded task runner. The main agent decides how to work; the extension provides small deterministic tools for current work state, project memory, delegation, search, and safety.

Core ideas

1. Project understanding first — use PROJECT.md when useful, and update project memory only after user confirmation.
2. Autonomous work loop — understand → plan → execute → verify → decide continue/fix/ask/finish.
3. Concentrated questions — ask the user only for real decisions or blockers, with recommended answers.
4. Current work area — .ouroboros/ is the current workbench, not a multi-run task manager.
5. Thin runtime — no runner, no task scheduler, no per-run authorization, no active run pointer.

Runtime tools

Tool	Purpose
oo_start_work	Initialize the current .ouroboros/ work area from a workflow and fixed intent stages. Does not overwrite active/blocked work.
oo_status	Show current work and work.md recovery summary (updated / next).
oo_note	Append a durable project discovery to .ouroboros/memory/discoveries.md.
oo_memory	Read-only PROJECT memory and discovery ledger status/audit.
oo_memory_apply	Write user-confirmed PROJECT memory content, changelog entries, and discovery decisions by discovery id.
oo_finish_work	Finish, abandon, or block current work with verification, final summary, and warning-only acceptance/memory checks.
oo_onboard_preflight	Read-only onboarding preflight for PROJECT/memory status, git freshness, and candidate docs.
oo_config	Read or create .ouroboros/config.json; redacts API keys in output.
oo_subagent	Run bundled subagents. Saves artifacts to .ouroboros/artifacts/ when current work exists.
oo_search	Web search via Exa or Tavily.
oo_fetch	Fetch and extract web page content. Use after oo_search for full details.
oo_acceptance_check	Warning-only mechanical audit of current goal/work before finishing.

Slash commands

Command	Purpose
/ouroboros-status	Show a short status hint and continuation guidance.
/oo-init	New project initialization prompt (requirements, tech selection, project generation, PROJECT.md).
/oo-onboard	Prompt the agent to run the onboarding flow. Does not write files automatically.
/project-memory	Prompt the agent to process current discoveries. Does not edit PROJECT.md automatically.

Slash commands are hints, not automation pipelines.

Current work layout

.ouroboros/
|-- goal.md
|-- work.md
|-- memory/
|   |-- PROJECT.md
|   |-- PROJECT.changes.md
|   |-- PROJECT.backup.md
|   |-- brand-spec.md
|   `-- discoveries.md
|-- config.json          # local config; never auto-clear
|-- archive/             # optional manual archive; not runtime state
`-- artifacts/
    `-- index.md

memory/ is durable project memory and is not cleared by normal work cleanup. brand-spec.md is optional visual identity memory used by ui-design. work.md is the main agent's current plan and recovery context. Frontmatter uses:

updated: <timestamp>
next: "..."
status: active | done | blocked | abandoned
workflow: simple | complex

To continue, ask naturally; the agent should call oo_status and read .ouroboros/goal.md, .ouroboros/work.md, and relevant artifacts.

Starting work

For a new user task, the agent should choose a global workflow and fixed intent stages before calling oo_start_work. Lifecycle/runtime operations such as continue, finish, status, config, or memory tooling are handled with the corresponding internal tools instead of starting new work.

Example:

oo_start_work({
  title: "analyze current project",
  objective: "Explain the current project structure and key risks.",
  workflow: "simple",
  stages: [{ intent: "understand", summary: "Read relevant docs/code and explain project structure" }],
  successCriteria: ["Explanation is backed by code/doc evidence"],
  routingRationale: ["The user asked for project understanding that benefits from recoverable work context"]
})

If active or blocked current work already exists, no files are overwritten. The agent should call oo_status, then continue, finish, abandon, or block the existing work before starting new work. Completed or abandoned work is cleaned automatically by the next oo_start_work; .ouroboros/memory/ is never deleted by start.

Bundled skills and agents

• ouroboros — workflow protocol and runtime integration.
• web-design-engineer — design protocol used by ui-design for visual direction, brand specs, and UI critique.

Agent	Role
explorer	Read-only project exploration.
web-researcher	External web research only.
implementer	Implements one clear vertical slice and verifies it.
spec-reviewer	Read-only task/slice compliance review.
acceptance-reviewer	Read-only current-work implementation acceptance.
adversarial-reviewer	Read-only plan/design challenge review.
looker	Vision/image analysis via configured model.

Configuration

Local project config lives at .ouroboros/config.json and should not be committed. Use oo_config to inspect or create it.

Example:

{
  "visionModel": "anthropic/claude-sonnet-4-20250514",
  "exaApiKey": "...",
  "tavilyApiKey": "..."
}

Optional global safety config lives at ~/.pi/ouroboros/safety.json and is never auto-created:

{
  "extraBlockPatterns": [{ "pattern": "drop\\s+database", "reason": "destructive SQL" }]
}

User config can add block patterns; it cannot override built-in catastrophic rules.

Documentation

• Design
• Usage
• Testing
• Release Process
• Workflow Scenarios
• Glossary

Package and releases

• Release notes live in CHANGELOG.md.
• The npm release process is documented in docs/release.md.
• GitHub Actions publishes from matching v<package version> GitHub Releases using the repository NPM_TOKEN secret.
• The project logo lives at docs/assets/pi-ouroboros-logo.png.

Development

npm install
npm run verify
npm run pack:dry-run

Local pi session:

export OUROBOROS_DEV_EXTENSION_PATH="$PWD/index.ts"
pi -e ./index.ts --skill ./skills/ouroboros/SKILL.md --prompt-template ./prompts/implement.md

License

MIT