Skip to content

Engineering Plan Workflow

How the Engineering Lead uses .plan.md files to self-manage implementation.

The Level 1 loop

Every creative stage (Frame, Design, Implement, Document) follows this internal cycle:

Plan ──→ Do ──→ Self-check ──→ Review ──→ Complete
  ↑        │                      │           │
  │        │  issue found         │           │
  │        └──→ back to Do ◄──────┘           │
  │                                           │
  └────── changes required ◄──────────────────┘

This is self-driven. No Notion. No PR. No human approval. Just you and the code.

Plan file location

projects/{repo}/plans/{stage}-{desc}.plan.md

When a plan is complete and Review passes, move it to:

projects/{repo}/plans/done/{stage}-{desc}.plan.md

Plan template

# [Stage: frame / design / implement / document] — [Task name]

## Outcome
What must be true when this is done.

## Artifacts

### Create
- [ ] `path/file` — purpose

### Modify
- [ ] `path/file:function` — change description

### Remove
- [ ] `path/file` — why

## Docs to update
- [ ] `README.md` — section to add/change

## Checks
- [ ] Tests pass
- [ ] Lint clean

## Review log
| Attempt | Verdict | Issues |
|----------|---------|--------|

Per-stage plan examples

Frame plan

# Frame — German Real Estate Intelligence

## Outcome
Architecture decisions recorded. Scope boundary clear. Tech stack chosen.

## Artifacts

### Create
- [ ] `docs/architecture.md` — architecture decision record

## Docs to update
(none)

## Checks
- [ ] All decisions have a rationale
- [ ] Estate constraints verified (Lab: deploy to konstant, no custom domain)
- [ ] What's OUT of scope is explicitly listed

## Review log
| Attempt | Verdict | Issues |
|----------|---------|--------|

Design plan

# Design — German Real Estate Intelligence

## Outcome
Data model, API surface, component tree, and state flow are documented.

## Artifacts

### Create
- [ ] `docs/data-model.md` — entities, relationships, constraints
- [ ] `docs/api.md` — endpoints, request/response shapes, auth
- [ ] `docs/components.md` — component tree, props, state per component
- [ ] `docs/state-flow.md` — user flows, state transitions

## Docs to update
(none)

## Checks
- [ ] Data model covers all scenarios from requirements
- [ ] API endpoints match the component needs
- [ ] State flow covers edge cases
- [ ] Brand decisions documented (colors, fonts, tone)

## Review log
| Attempt | Verdict | Issues |
|----------|---------|--------|

Implement plan

Multiple plans per stage — one per feature chunk.

# Implement — Tax scenario calculator

## Outcome
Users can input property data and receive tax scenario projections.

## Artifacts

### Create
- [ ] `src/calculator/tax.py` — tax computation engine
- [ ] `src/calculator/scenarios.py` — scenario builder
- [ ] `src/components/TaxForm.tsx` — input form
- [ ] `src/components/TaxResults.tsx` — results display
- [ ] `tests/test_tax.py` — unit tests
- [ ] `tests/test_scenarios.py` — scenario tests

### Modify
- [ ] `src/app.py:42` — add calculator route
- [ ] `src/components/App.tsx:15` — add TaxForm to navigation

### Remove
(none)

## Docs to update
- [ ] `README.md` — add tax calculator section to features

## Checks
- [ ] All tests pass
- [ ] Lint clean
- [ ] Tax computation matches manual calculation
- [ ] UI renders correctly in all screen sizes

## Review log
| Attempt | Verdict | Issues |
|----------|---------|--------|

Document plan

# Document — German Real Estate Intelligence

## Outcome
All documentation is current and accurate.

## Artifacts

### Create
- [ ] `docs/user-guide.md` — how to use the app

### Modify
- [ ] `README.md` — update setup instructions with actual dependencies
- [ ] `README.md` — update feature list with completed features

### Remove
- [ ] `docs/old-design-notes.md` — superseded by architecture.md

## Docs to update
- [ ] `catalog.md` — add lab entry with description, URL, stack

## Checks
- [ ] README setup instructions work on a fresh clone
- [ ] No broken links in docs
- [ ] Catalog entry is accurate

## Review log
| Attempt | Verdict | Issues |
|----------|---------|--------|

The Review step

Review is the critical gate. When you get to Review:

  1. Re-read the plan file from top to bottom
  2. Open every file listed in Artifacts. Compare what you planned to what exists
  3. Run every check. Don't assume they pass — run them
  4. Only mark Complete if every item is done AND every check passes
  5. If anything is missing or wrong:
  6. Uncheck the item [ ]
  7. Add a row to the Review log with what's wrong
  8. Go back to Do

This is self-review. You are the reviewer and the implementer. No rubber-stamping.

Type B — Checklist stages

For Verify, Promote, and Deploy, use a simpler checklist:

Run ──→ Assess ──→ Fix ──→ Complete

No plan file needed. The checklist is implicit:

Verify checklist: - Test suite passes - Lint clean - Typecheck passes - No regressions from previous version

Promote checklist: - Version bumped in pyproject.toml or equivalent - Changelog updated with this release's changes - Git tag created - CI green on the tag

Deploy checklist: - Deploy config syntax valid - If Lab: app responds on https://app-name.hectorsanchez.eu - If Portfolio-org: app responds on its domain - Health check endpoint returns 200 - Estate-appropriate checks pass (Lab: catalog entry; Portfolio-org: SSL, DNS)

Working directory

All plans live in the repo's projects/ workspace, inside the cloned repo directory:

projects/{repo}/
├── plans/
│   ├── implement-tax-calc.plan.md      # active
│   ├── implement-auth.plan.md          # active (parallel)
│   └── done/
│       └── frame-architecture.plan.md  # completed
└── src/                                # application code

Relation to Notion

  • Plan stage (Level 2 Workflow Stage=frame through Workflow Stage=document) is updated in Notion only when a Level 1 loop completes
  • Plan files are local evidence, not synced to Notion
  • When the final Level 2 stage (Document) completes, mark the Task Status=Done
  • Portfolio Manager reads this and creates the next Task