Project creating

Creating a Project

Precondition

An active intent must exist with enough context to define a project — at minimum: name/slug, path, and key decisions from ## Context > ### Decisions.

Workflow

1. Determine Project Identity

• Slug: derived from intent name (kebab-case, 2-4 words) or user-specified
• Path: from ~/.plastic/config.yml project_roots (first entry as default), or user-specified
• Confirm path with user before creation

2. Create Project Directory

mkdir -p <project_root>/<slug>
cd <project_root>/<slug>
git init

3. Run plastic-install --local

Invoke plastic-install --local in the project directory. This creates:

.plastic/
├── store/
├── INDEX.md
└── config.yml

4. Populate AGENTS.md

Create AGENTS.md in the project root from the skeleton in references/project-scaffolding.md ("AGENTS.md skeleton"): read it now and fill in the project name, governing intent IDs, decisions, and project-specific rules.

5. Create Tactical Mirror

Create the first intent in the project's store at ~/.plastic/projects/{slug}/store/ using the frontmatter, sections, and INDEX.md line in references/project-scaffolding.md ("Tactical mirror intent"), including the Hub multi-intent variant if there is more than one founding intent.

Directory: ~/.plastic/projects/{slug}/store/1--{slug}/ File: ~/.plastic/projects/{slug}/store/1--{slug}/1--{slug}.md

6. Register in projects.yml

Read ~/.plastic/projects.yml and add the entry shown in references/project-scaffolding.md ("projects.yml registration block"). For Hub-spawned projects, parent references the primary founding intent.

7. Provision the Project Store

The provision-project-store verb is the single source of truth for store creation. Run it after the project is registered in step 6 (the provisioner requires registration), and before the QMD step:

ruby ~/.plastic/scripts/provision-project-store <slug>

This ensures ~/.plastic/projects/<slug>/store/ exists with .gitkeep, and writes INDEX.md and project.yml only if missing. It is idempotent, so it is safe even when the tactical mirror in step 5 already created the store directory. Do not create the store with an inline mkdir; the provisioner is the only place a store is made. For a project that is already registered but store-less, use the plastic-store-provisioning skill instead.

8. Mark Global Intent(s) Completed

For each founding intent:

1. Write ## Outcome in the intent file:

   "Spawned project <slug> at <path>. Decisions carried to AGENTS.md. Tactical mirror: project-<slug>:1."

2. Write outcome.md with full details (all decisions, project path, tactical mirror ID)
3. Update chain to include project-<slug>:1
4. Move from ## Active to ## Completed in ~/.plastic/INDEX.md (with today's date)

9. Framework Scaffolding

If decisions specify a framework, run the appropriate scaffolding command AFTER steps 3-4 (so scaffolding doesn't overwrite Plastic files or AGENTS.md):

Framework	Command
Rails	rails new <slug> [options from decisions] --skip-git (skip git — already initialized)
Node/npm	npm init -y
Ruby gem	bundle gem <slug>
Other	As specified in decisions

After scaffolding, verify AGENTS.md and .plastic/ still exist. If scaffolding overwrote them, restore.

10. Auto-commit Both Stores

cd ~/.plastic && git add . && git commit -m "feat: spawn project <slug> from intent <ID>"
cd <project> && git add . && git commit -m "feat: initialize project from intent <ID>"

11. Register the project store with QMD (optional)

If QMD is installed, register the new project's store as a search collection:

ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/store

qmd-sync no-ops when QMD is absent, so run it unconditionally. This adds the plastic-<slug> collection and indexes it.

12. Self-Check with validate-project

Before announcing, verify the spawn actually landed everything it claims to have created. Run:

ruby ~/.plastic/scripts/validate-project <slug>

If this exits 0, proceed to step 13. If it exits non-zero, STOP: do not proceed to Announce. Read the missing: and error lines it printed to stderr, fix the named gap(s), for example:

• missing project.yml or INDEX.md or store/: re-run ruby ~/.plastic/scripts/provision-project-store <slug> (step 7), then re-check
• missing project-root AGENTS.md: repeat step 4 (populate AGENTS.md at the project root, not ~/.plastic/projects/<slug>/)
• project directory missing on disk: repeat step 2
• not registered in projects.yml: repeat step 6

Re-run validate-project <slug> after each fix until it exits 0. Only a project spawn that passes this self-check moves on to be announced as created. A spawn that never verifies itself is exactly the bug this step exists to close (intent 190; the intent-26 spawn shipped with no project.yml and no root AGENTS.md, caught only weeks later by a doctor sweep).

13. Announce

Log in ## Insights of each founding intent:

"Project <slug> created at <path>. Tactical mirror: project-<slug>:1 (autonomous)"

Announce to user:

"Project <slug> created at <path>. AGENTS.md populated with [N] decisions from [founding intent IDs]. Tactical mirror 1 is now the active intent in the project store."

References

• Read references/project-scaffolding.md before steps 4-6, for the AGENTS.md skeleton, the tactical mirror intent format, and the projects.yml registration block
• Read references/hubs-projects.md for the full hub/project relationship model, project creation flow, and cross-linking conventions