Project creation

Filed under a -workflow- filename from the 2026-08-21 draft, when this was going to be a workflow. It ships as a skill (see the 08-22 ruling below). The filename is left alone because ~500 doc links are already broken (#833) and renaming adds to that.

Status: draft, revised 2026-08-22. Co-edited with the operator; her rulings are marked with the date they were given. Built: the project-creation skill, wired into day-plan Phase 6 and the project-manager dispatch rules. The first project folder is docs/projects/agent-workflow-hierarchy/. Extends: #928 docs: restructure planning into per-project folders, with a README as each project front door

---

Problem

There is no project. Work arrives as an issue, an agent builds it, and the docs it produces land wherever that agent decided: a spec here, a test run there, a worklog somewhere else. Nothing holds them together, so a person picking the work up later has to reconstruct it from git history.

docs/projects/ does not exist yet. docs/planning/ holds 103 loose files with no per-project grouping.

Goals

• A new piece of work gets a folder, and everything about it lives there.
• An agent scaffolds that folder the same way every time, rather than inventing a layout.
• A project is findable from GitHub, and GitHub is findable from the project.

Non-goals

• No migration. The 103 existing files in docs/planning/ stay where they are. This is the process going forward. (Operator ruling, 2026-08-21.)
• Not a launch-plan editor. See "What it may write" below.
• Not a replacement for issues. Issues stay the unit of tracking.

The design

What a project is

A deliverable area. Tasks live inside it. The operator's example: merchant data dashboards is a project; wiring up the data is one task, redesigning the dashboard is another.

Scale is not a constraint. Hundreds of projects is fine, because that is what a filesystem does. (Operator ruling, 2026-08-21, correcting an earlier objection in this design that 106 was too many.)

The folder

docs/projects/<project-name>/
  README.md          the front door: what this is, its issue, its current state
  planning.md        what gets done in what order, and what is out of scope
  design.md          the what and how, when there is a real decision
  implementation.md  execution notes, findings, anything the building produces
  testing.md         the manual test plan, written here and nowhere else
  logging.md         the worklog for this project

Six flat files, no subdirectories. (Operator ruling, 2026-08-22, superseding the 08-21 shape that had plan.md plus logs/ and implementation/ directories.)

Only README.md is mandatory. The rest appear when the work needs them, and the skill creates the ones the work calls for rather than scaffolding empty files nobody fills in.

The folder name is the project name. (Operator ruling, 2026-08-21.) A date may be appended where it helps filing, but it is not required, because the README is what identifies the project. Two agents cannot create the same project twice: the skill checks whether the folder exists before creating it.

Testing now always writes into the project. (Operator ruling, 2026-08-21.) docs/engineering/testing/runs/ stops being the destination for new test plans; the test-plan skill writes to docs/projects/<name>/testing.md instead. Existing runs stay where they are, per the no-migration rule.

Logs live in the project too, and the legacy log directory is archived. (Operator ruling, 2026-08-21.) docs/worklog/ stops taking new entries and is archived; a project's worklog is its own logging.md.

How it connects to the launch plan

The chain is project to issue to launch plan. (Operator ruling, 2026-08-22.) The project README links its issue, and that issue's body links its launch-plan row. The row also cites the issue in its last column, so the connection reads from either end and neither side has to guess.

Issue numbers remain the connector. What changed on 08-22 is that the issue now carries the plan link explicitly, rather than the two sides meeting only through a shared number.

Direct, never chained. A project issue goes straight onto its launch-plan row, one hop. An issue that links to another issue that links to a row is a chain, and chains break silently: on 2026-08-21 three unfinished plan rows were found pointing at closed issues, and one issue was backing two different rows, so closing it for one would have closed the other.

A project that maps to no launch-plan row has no plan link, and its README says so explicitly rather than forcing a fake one. Not all work is product work: the tmux fleet repair on 2026-08-21 is a real project and belongs to no row.

It files its own issue rather than borrowing one. A borrowed issue is how one issue ended up backing two rows. Consolidation may still find a canonical issue that already tracks the work, and adopting that one is not borrowing.

What it may write

It writes	It does not write
The project folder and its files	Anything else in the launch plan
A new GitHub issue for the project	Status, priority, descriptions, or new rows
The issue number into the matching launch-plan row

Contextual changes to the launch plan are a separate job. (Operator ruling, 2026-08-21.) This keeps a scaffolding step out of judgment calls about what the plan should say.

The steps

The live version is the project-creation skill. This is the design record.

1. Take the project name and a description of the work.
2. Consolidate: search open issues, PRs, and prior specs for overlap, and surface the canonical issue if the work is already tracked. (Non-negotiable rule 13.)
3. Create docs/projects/<project-name>/ and write the README from what step 2 found.
4. File the issue.
5. Present the candidate launch-plan rows and ASK which one this is, or none. Write the issue number into the chosen row. If none, record that in the README.
6. Report what it created and what it deliberately did not.

Step 2 is the one that has to run every time: consolidation is exactly the step an agent skips when it already believes it knows the answer.

This ships as a SKILL, not a workflow. (Operator ruling, 2026-08-22, superseding the 08-21 reasoning that reached the opposite conclusion.) The tradeoff is real and worth stating: a skill is prose an agent may walk past, so nothing forces step 2. What buys it back is that the skill is invoked from a fixed point in another procedure (day-plan Phase 6) rather than left to an agent's judgment about when a project is needed. If consolidation is later observed being skipped, promoting step 2 alone into a workflow the skill calls is the smallest fix.

Key decisions

Decision	Ruling
A project is a deliverable area, tasks live inside it	Operator, 2026-08-21
Hundreds of projects is fine	Operator, 2026-08-21
No migration of docs/planning/	Operator, 2026-08-21
Issue numbers are the connector, not cross-links	Operator, 2026-08-21
It writes the issue number into the plan and nothing else	Operator, 2026-08-21
Six flat files, no subdirectories	Operator, 2026-08-22
It ships as a skill, not a workflow	Operator, 2026-08-22
The issue carries the launch-plan link in its body	Operator, 2026-08-22
The PM invokes it after the agenda is approved	Operator, 2026-08-22

Open questions

1. RESOLVED. Folder name is the project name; date optional; existence check prevents duplicates.
2. RESOLVED. Testing always writes into the project.
3. RESOLVED. Logs live in the project; docs/worklog/ is archived.
4. Discovering the launch-plan row. Step 5 has to match the work to a row, and matching automatically is the kind of guess that produced five wrong issue links already. Resolution: it ASKS. It presents the candidate rows it found and the operator picks, or says none. This is the same "grill me for the specifics" step the operator asked for after agenda approval, arriving here for the same reason: a question costs one tap, and a wrong guess costs a link nobody notices is wrong for months.

Follow-on: scaffolding skills per document type

The test-plan skill already produces a consistent format for one document, which is why test plans read the same every time and the others do not. The same is wanted for the README, the design, and the plan, so a project's documents follow a format rather than each agent inventing one. (Operator note, 2026-08-21.)

One skill per document type, matching test-plan. (Operator ruling, 2026-08-21.) So alongside the existing test-plan, a project needs a skill for README.md, one for planning.md, one for design.md, one for implementation.md, and one for logging.md.

The reason one-per-type wins over one skill covering everything: a single skill would have to branch on document type, and a branch is where an agent picks the wrong arm. test-plan works because it has exactly one job and no way to do a different one.

Still unbuilt. It no longer BLOCKS creation: project-creation carries a README template inline so a project can be created today. Each document skill that lands replaces the corresponding inline template.

Related

• #928 is the canonical issue and carries the measured cost of the wider restructure.
• #833, broken doc links, is the main risk if anything ever does move.
• docs/engineering/guides/DIRECTORY_DEFINITIONS.md needs a line saying which structure is which during the transition.