Inception: from an idea to queued work
Inception is the first phase of the AI-driven development lifecycle: a person
says what they want, AI breaks it down and asks what it still needs to know,
and a person approves the plan before any code is written. In Orion that
phase is two commands, orion new then orion plan, and it ends with a
repository on GitHub and a ticket tree in Jira for
Construction to work.
| Phase | Orion |
|---|---|
| Inception | orion new, then orion plan (this page) |
| Construction | orion watch, which runs orion work for each ticket |
| Operations | Not built yet: incidents from a shipped product do not reach Orion |
1 · You describe it: orion new
orion new is Orion's only interactive step, and no agent runs in it.
Every later stage runs without a person present, so the questions are asked
here.
- Orion checks that your tracker account can create a project before asking anything.
- It takes the idea from an idea already written up in the tracker (pass its key and the interview is skipped), a file or URL (read word for word), or your answer to "What do you want built?".
- It asks five questions: who it is for, what is wrong for them today, how you will know it worked, what is out of scope, and any constraints. Enter leaves one unanswered.
- You name the project, and its key is derived from the name and made unique.
- It shows the description, key and site, and creates nothing before you say yes.
- It creates the tracker project with you as lead and your answers as its description. An interviewed idea is also filed on the discovery board; an idea that came from there is linked back to the new project.
orion new creates no workspace, repository or Slack channel; orion plan
does (ADR 0013).
Without a terminal, pass the key of an idea that is already written up.
2 · Agents break it down: orion plan
orion plan KEY reads the project and creates its workspace under
~/.orion, one per tracker project
(ADR 0012).
Running it again resumes that workspace; a different project whose name
slugifies to the same workspace is refused, naming the owner. It asks once
whether to run the chain, pausing after each stage, and where your own copy
of the repository should go.
The agent steps (claude -p) run inside the sandbox,
each reading what the step before it committed, starting from your answers.
| Step | Run by | Writes |
|---|---|---|
| toolkit | Orion | installs spec-kit into the repository, once; nothing to do when no stage uses it |
| intent | pm | docs/intent/<slug>.md: your answers from orion new, broken down into what is being built and why |
| constitution | architect | .specify/memory/constitution.md: the project's principles, seeded from orion.json's gates and the intent |
| spec | architect | specs/001-<slug>/spec.md: requirements and design |
| spec-branch-sync | Orion | moves the sandbox back to develop after spec-kit's own branch checkout |
| plan | architect | plan.md, then tasks.md through spec-kit's tasks step |
| analyze | architect | no file: a read-only check that spec, plan and tasks agree with each other and with the constitution |
| scaffold | devops | the repository skeleton, to the OpenSSF baseline |
Constitution, spec, plan and analyze go to spec-kit by default; a project
can point any of them at another toolkit in toolkit.stages
(System architecture).
The question loop
Intent, spec and plan each list the open questions they could not answer
from what came before, and a stage with open questions is not done, so the
next stage does not design on a guess. orion answer walks you through them
and writes your answers into the artifact; run orion plan KEY again and the
stage runs with them.
Analyze stops the chain when spec, plan and tasks contradict each other or it finds a critical issue.
3 · Orion stands it up; you approve the plan
Orion runs these steps in its own process, and they call no model except in one case under decompose.
| Step | Does |
|---|---|
| evals | eval cases and a harness from the spec's agentic design; nothing to do when the spec has none |
| remote | creates the GitHub repository, pushes main and develop, and protects both |
| scaffold-publish | pushes the scaffold branch and opens its pull request into develop |
| decompose | builds the Epic / Story / Task tree in Jira |
| release | attaches the tree to a tracker version; only with --release vX.Y.Z |
| clone | your own copy of the repository, where you asked for it |
You approve the plan at decompose. From tasks.md, Orion shows the whole
tree and creates it only on one yes. Every story and every
epic-level task an agent can do gets the ORION label, so the watch will pick
it up; the epic itself and a story's sub-tasks do not, because the story
works its own sub-tasks. A task marked HUMAN is created but never queued. A
re-run finds what the last run made through the orion-spec-<feature>
label, links it, and creates only the rest.
With no tasks.md, the pm agent runs your toolkit's decomposition command
(/pm-plan by default) in the sandbox instead. That is the one step here
that can spend.
The GitHub repository is created only after every earlier gate passes, because it is hard to undo, so a chain stopped at a gate leaves nothing to delete.
When every step is done, the project is registered for the watch and the
chain prints next: orion watch KEY.
The database architect
When the idea involves storing data, orion plan names the database
architect and the command that runs it, orion run <id> --stage database.
It recommends a database, waits for a person to confirm that choice in
Slack, and then designs the schema
(Advisors and decisions).
Resuming and stopping orion plan
| Pauses after every stage | "Continue to the next step?" defaults to no; answering no stops the chain and prints how to resume. |
orion plan KEY again | Steps whose work is already there are skipped. |
--from STEP | Redoes from that step onward, even where the work exists. |
| A stage fails, or reports itself BLOCKED | The chain stops at that stage and prints the command that re-runs it. |
| Weekly budget checkpoint | If spending has crossed a checkpoint, the chain stops before dispatching anything. |
--dry-run | Shows which steps would run and which would be skipped; creates and spends nothing. |
| No terminal | Without someone to answer the pauses, orion plan prints the first command and stops, unless --yes was passed. |