Skip to content
DivineSWE

Workflows

DivineSWE maps all software development work onto a single research → plan → implement framework. Every cycle follows this covenant, regardless of where it begins. What varies is the entry point.

The default path: the Avatar forges, and for involved work the Oracle envisions first. /divineswe:avatar-forge plans the commit units and implements them in the live session, tests first, with 4eyes auditing every major unit before it is committed, and records the evidence in the spec until you check it. A plain ad-hoc ask needs no spec from you: the Avatar writes its own Mandates into one, shows them, and carries on unless you stop it. For a more involved feature or change, /divineswe:oracle-envision comes first — the Oracle researches it with you, brainstorms concepts, sweeps for gaps and opportunities, and writes a forge spec: Mandates, each with an Accept: line naming its proof. The Book cycle — oracle-consult book → prophet-fulfill — is deprecated; it is described at the end of this page only for Books already in flight.

The Framework: Research → Plan → Implement

Research is the first act. Before a single line of code is written, the problem is understood. Root cause is identified. The solution space is explored. Ambiguities are surfaced and resolved. This is Oracle’s domain — and Loki-Doubt’s arena for one adversarial challenge when the Oracle envisions.

Plan is the second act. Research becomes scripture. A forge spec of Mandates, each with the proof it owes, is written by oracle-envision for involved work or by the Avatar itself for a plain ask. The covenant is now written in stone.

Implement is the third act. On the default path the Avatar forges the spec in the live session, unit by unit, tests first, with 4eyes auditing every major unit before it is committed. Tests are written before code. Every implementation is audited and verified before it merges.

The Three Entry Paths

Path 1: avatar-forge, envisioned first when the work is involved

The default path for new features and architectural changes.

/divineswe:oracle-envision  →  /divineswe:avatar-forge     # involved work
/divineswe:avatar-forge                                     # a clear change, described

When to use: You have a clear feature intent, a refactor target, or a new system to build. You know the “what” and need DivineSWE to help you work out the “how.”

What happens:

  1. For involved work, oracle-envision opens the design. You describe your vision; the Oracle frames it in as many questions as it needs, up to twenty, grounds itself in the code (and, for an outside problem, in cited prior art), offers up to three plausible concepts with one pick, sweeps the chosen one for gaps and opportunities, and summons one Loki-Doubt pass. Every candidate takes the Oracle’s recommended ruling — Now, Later or No — unless you mark it otherwise; no task breakdown.
  2. The Oracle writes the forge spec to docs/specs/forge-<slug>.md and points you to it by its path, with a short summary; it pastes the spec into the chat only when you ask.
  3. You approve it; the Oracle verifies it with the forge-spec gate, commits it and hands it off. The envisioning is complete.
  4. avatar-forge reads the spec — or, for a clear change, your description, which it writes into a spec of its own — plans the commit units, and forges them in the live session, tests first, with 4eyes auditing every major unit before commit.

Path 2: root-cause-analysis → avatar-forge

The path for bugs, crashes, exceptions, and recurring failures.

/divineswe:root-cause-analysis  →  /divineswe:avatar-forge

When to use: Something is broken and you need to understand why before you can fix it. You have a symptom but not a root cause.

What happens:

  1. root-cause-analysis opens a systematic investigation. You describe the failure. Oracle traces the failure to its origin — identifying the specific code path, state condition, or invariant violation that caused it. The investigation produces a diagnosis document.
  2. Armed with the root cause, you describe the fix to avatar-forge — or envision it first with oracle-envision when the fix itself needs designing. The Mandates trace to the diagnosis.
  3. avatar-forge forges the fix, tests first, with 4eyes auditing every major unit.

The order is deliberate: root cause analysis is a research phase, and research must complete before planning begins. Jumping straight to a fix without a diagnosis risks fixing a symptom while the real cause persists.

Path 3: prophet-full-audit → (optional: avatar-forge)

The path for adversarial inspection outside any active development cycle.

/divineswe:prophet-full-audit  →  .divineswe/audits/<slug>.md  →  (optional: its Forge Prompt to avatar-forge)

When to use: You want a security and quality audit of what already stands without triggering a full development cycle. Use before a release, after a major merge, or whenever you want an independent adversarial review.

What happens:

  1. prophet-full-audit summons 4eyes (a single-pass correctness and security review) and Loki-Exploit (an adversarial probe) through avatar summon, over the scope you name — a whole codebase, a directory, a file, a glob, or the work since a commit. No Book is required. No IMPLEMENT phase runs.
  2. Occam weighs Loki’s findings before any of them reaches the report, and every finding is checked against the forge specs and open vows that touch the scope.
  3. One report lands at .divineswe/audits/<slug>.md — an executive summary, CRITICAL/HIGH/MEDIUM/LOW findings, the seats’ perspectives and recommendations — ending in a Forge Prompt.
  4. To fix what it found, hand the Forge Prompt to avatar-forge — after oracle-envision when a fix needs designing — or address the findings by hand.

The Book cycle (deprecated)

oracle-consult book → prophet-fulfill, with its auto-chain prophet-revelation and its recovery skill prophet-resume, is deprecated. Nothing new should start there: design with /divineswe:oracle-envision and build with /divineswe:avatar-forge. The deprecated skills still run for a Book already in flight — Prophet walks it through INIT → TEST → IMPLEMENT → AUDIT → MERGE → VERIFY → WRAP UP → SEAL, and the deprecated prophet-resume re-enters an interrupted cycle from .divineswe/session-state.json.

Session Recovery

Orchestration sessions can be interrupted — network drops, process crashes, context window exhaustion during a long build. DivineSWE is designed to survive these failures, and forge work needs no resume skill: run /divineswe:avatar-forge <spec> again and the Avatar picks up from what the spec’s ## Fulfilment does not yet record.

Further Reading

  • Quick Start — install and forge your first change
  • Skills — complete skill reference table
  • Overview — the three plagues, the covenant, the eight-phase cycle
  • Architecture — full state machine, phase table, prophecy execution model