When the Plan Already Exists: Planned Pipeline Mode

Originally, AI Software House owned the whole journey from idea to pull request.

Give it a requirement, and it would write the PRD, design the architecture, generate tests, implement code, review the PR, run fixes, and push the branch.

That is useful when the input is still only a rough requirement.

Sometimes, though, I have already done the planning.

I may have worked through the feature with Superpowers, written the spec by hand, or already reviewed the implementation plan with somebody else.

Running those inputs through another PM and architect does not add much. It can even replace an approved decision with a slightly different one.

That is why I added planned mode.

Planning and execution are different jobs

Spec writing is a reasoning-heavy task.

You want the model to ask better questions, explore tradeoffs, find ambiguous requirements, and produce a plan that can survive review.

Implementation is a loop-heavy task.

You want the system to write tests, review them, implement against them, run the suite, repair failures, review the code, and open a PR.

I found it more useful to treat these as separate jobs.

Superpowers is good at the first part: turning an idea into a spec and implementation plan.

AI Software House is good at the second part: forcing the build through a repeatable pipeline until there is code, tests, review, and a pull request.

planned mode connects the two.

The input format

The watcher can now read Superpowers artifacts directly from a GitHub issue.

You can paste the spec and plan into the issue body or comments:

```superpowers-spec
# Spec
...
```

```superpowers-plan
# Plan
...
```

Or you can commit the files and reference them:

Superpowers-Spec: docs/superpowers/specs/auth.md
Superpowers-Plan: docs/superpowers/plans/auth.md

The watcher resolves referenced files from the target repo first, then the tracker repo.

That matters because the spec and plan often belong with the application being changed, not with the orchestration repo.

The pipeline

The new pipeline is ordinary YAML:

stages:
  - superpowers_ingest
  - qa_planner
  - qa_write
  - loop:
      max: 3
      until: APPROVED
      stages:
        - tdd_review
        - qa_fix
  - contract_validate
  - tier_review
  - junior_engineer
  - senior_engineer
  - loop:
      max: 10
      until: TESTS_PASS
      stages:
        - test_fix
  - loop:
      max: 5
      until: APPROVED
      stages:
        - reviewer
        - senior_engineer
  - deploy_tester
  - deploy_fix

The first stage is the important one.

superpowers_ingest maps the external artifacts into the normal pipeline contract:

spec becomes prd
plan becomes design
acceptance criteria become QA inputs
plan tasks become implementation modules

After that, the rest of the system does not need to know where the plan came from.

The QA planner sees a PRD. The engineer sees a design. The reviewer sees generated code. The deploy tester sees a branch.

From that point onward, it is the ordinary pipeline. Keeping this part boring was intentional.

Why review the tests first?

planned mode starts with tests on purpose.

An approved plan does not make generated tests automatically correct.

A test can assume the wrong import path. It can mock a FastAPI dependency incorrectly. It can assert behavior that was never in the spec. If the engineer implements against bad tests, the loop wastes time.

So planned mode inserts a review/fix loop before implementation:

- loop:
    max: 3
    until: APPROVED
    stages:
      - tdd_review
      - qa_fix

The TDD reviewer checks the generated tests before the engineer starts coding.

This catches a bad import, mock, or interpretation before production code has been written around it.

CLI mode

The same flow works without the watcher:

python main.py --pipeline planned \
  --spec docs/superpowers/specs/auth.md \
  --plan docs/superpowers/plans/auth.md \
  --repo owner/repo \
  "Build auth feature"

--spec and --plan must be provided together. A plan without a spec is not enough context. A spec without a plan is just another requirement.

Watcher setup

For issue-driven runs, map a label to the planned pipeline:

labels:
  ai-planned:
    pipeline: planned

Then create an issue with the spec and plan, or with references to the files, and apply ai-planned.

The watcher does the rest:

read the issue and prior comments
resolve the spec and plan
load pipelines/planned.yaml
run the orchestrator with those artifacts
open the implementation PR

No new watcher path. No new orchestrator subclass. No special GitHub workflow.

Just another label mapped to another pipeline.

What changed architecturally

The code change is fairly small, but it changes where the pipeline boundary sits.

The pipeline is now less opinionated about where upstream planning comes from.

The original flow was:

requirement -> PM -> architect -> QA -> engineer

The planned flow is:

external spec/plan -> ingest -> QA -> engineer

Both flows use the same downstream machinery.

That separation matters. The orchestrator should not force every project through the same planning process. Sometimes the plan should be generated inside the pipeline. Sometimes it should be produced outside, reviewed separately, and handed in as a contract.

planned mode makes that boundary explicit.

Why this boundary helps

This is the same pattern as the naming contract.

I keep coming back to the same lesson: do not ask a downstream agent to rediscover a decision that already exists upstream.

If the architect has exact field names, write a contract.

If Superpowers has already produced a spec and plan, ingest them.

The pipeline improves when agents stop re-deciding things that have already been decided.

Planning is where I want careful questions and judgement. Execution is where I want repeatable loops and hard checks.

planned mode lets me use a strong planning process without throwing away the execution machinery I already trust.

Part of the AI Software House series.