Fold idea-workshop into /new-project; add placement reference
Harvest the retired idea-workshop skill into the current new-project flow: - form-factor gate (is this even a standalone repo, or a feature/skill/agent of something that exists? bail + reroute if so) - worth-building gate at sign-off (build effort + ongoing tax -> BUILD/PARK/ADOPT) - placement step that walks the new guides/placement.md - falsifiable-exit substance rule and a posture section - architectural decisions land in the new repo's AGENTS.md ## Decisions section, absorbing the old DECISIONS.md function (no separate ADR file) Add guides/placement.md (ported from the skill) and point how-i-work.md at it. Its infra facts are UNVERIFIED (one-shot from chat history) and flagged for a review pass with me (ROADMAP item 7).
This commit is contained in:
+107
-51
@@ -10,10 +10,25 @@ You are bootstrapping a brand-new project under `~/Projects`. You run in the **m
|
||||
thread** — scoping a new project is a conversation, not a delegated job — so you talk to
|
||||
the user and ask for the judgment calls. Do not behave like a subagent.
|
||||
|
||||
The arc: **locate the seed → workshop the scope → get the plan signed off → scaffold →
|
||||
publish → close the capture loop.** Nothing lands on disk until Phase 3, and nothing is
|
||||
created without the user's sign-off in Phase 2. Work the phases in order; at each decision
|
||||
point, ask and wait — don't guess on anything that lands on disk.
|
||||
The arc: **locate the seed → frame it and confirm it's even a repo → workshop the scope →
|
||||
get the plan signed off → scaffold → publish → close the capture loop.** Nothing lands on
|
||||
disk until the scaffold phase, and nothing is created without the user's sign-off at the
|
||||
plan gate. Two gates protect that work: a **form-factor gate** early (is this even a
|
||||
standalone repo?) and a **worth-building gate** at sign-off (is it worth the build *and* the
|
||||
ongoing tax?). Work the phases in order; at each decision point, ask and wait — don't guess
|
||||
on anything that lands on disk.
|
||||
|
||||
## Posture (how to run the whole conversation)
|
||||
|
||||
Be a collaborator, not an interviewer. **Propose a draft answer and ask for corrections**
|
||||
rather than asking open-ended questions — the user is an expert on his own stack and intent,
|
||||
so a wrong draft he can fix in five words beats a questionnaire. At most a focused question
|
||||
or two per turn; one is better. Mine context before asking anything — the inbox seed, the
|
||||
other repos' conventions, memory, this conversation — and never ask what's already answered.
|
||||
**Scale the ceremony to the idea:** a one-off script might clear every gate in two turns; a
|
||||
new long-running service deserves the full walk. And **push back** — if the idea has a fuzzy
|
||||
user, a job an existing tool already does, or a "Phase 0" that's secretly three phases, name
|
||||
it. A workshop that only validates is worthless.
|
||||
|
||||
## Phase 0 — Locate the seed
|
||||
|
||||
@@ -27,51 +42,90 @@ point, ask and wait — don't guess on anything that lands on disk.
|
||||
- Settle on a **working name** early (kebab-case; it becomes the folder and the repo name).
|
||||
Confirm `~/Projects/<name>` does not already exist before going further.
|
||||
|
||||
## Phase 1 — Workshop the scope (the high-value step)
|
||||
## Phase 1 — Frame, then the form-factor gate
|
||||
|
||||
This is the point of the command — don't rush it to get to scaffolding. Like `/roundup`,
|
||||
the reasoning is the user's; you're drawing it out, not deciding it. Work through these a
|
||||
focused question or two at a time:
|
||||
Before workshopping a repo's scope, confirm it *should* be a repo. First draft a **thin
|
||||
frame** — a one-line objective and the single job-to-be-done — just enough to judge form, no
|
||||
more. Then walk the gate:
|
||||
|
||||
- **Objective** — what the project is for, in a sentence or two. What does "working" look
|
||||
like for v1?
|
||||
- **Non-goals** — what it explicitly will *not* do (the cheapest way to keep scope honest).
|
||||
- **Stack** — language, framework, datastore, packaging target (a StartOS `s9pk`?). Lean on
|
||||
the conventions in the user's other repos rather than inventing.
|
||||
- **What form should this take?** Standalone repo / a feature of an existing repo / a skill /
|
||||
an agent / a slash-command / a one-off script. Lean on what already exists: could one of
|
||||
the user's current repos absorb this as a feature far more cheaply than a new repo carries
|
||||
its own lifecycle?
|
||||
- **Does it already exist?** Check the user's own repos first, then OSS and the Start9
|
||||
marketplace. If an existing tool does ≥80% of the job, present the best one or two
|
||||
candidates honestly, including the case for adopting them. The cheapest project is the one
|
||||
you don't build, and finding that out in minute ten beats finding it out in week three.
|
||||
- **Outcome.** Only **a standalone repo that doesn't already exist** continues to Phase 2.
|
||||
If the right home is a feature/skill/agent/command of something that exists, or an existing
|
||||
tool wins, **stop and reroute gracefully** — re-capture the idea to `INBOX.md` tagged for
|
||||
the host repo (or point at the skill/agent authoring path), tell the user plainly why a
|
||||
standalone repo is the wrong shape, and don't scaffold. Bailing here is a success, not a
|
||||
failure.
|
||||
|
||||
## Phase 2 — Workshop the scope (the high-value step)
|
||||
|
||||
This is the point of the command — don't rush it to get to scaffolding. Like `/roundup`, the
|
||||
reasoning is the user's; you're drawing it out, not deciding it. Hold the posture above and
|
||||
work through these a focused question or two at a time:
|
||||
|
||||
- **Objective & non-goals** — what the project is for in a sentence or two, what "working"
|
||||
looks like for v1, and — the cheapest way to keep scope honest — what it explicitly will
|
||||
*not* do.
|
||||
- **Placement** — read `~/Projects/standards/guides/placement.md` and walk its decision
|
||||
sequence against this idea: sensitivity/sovereignty, runtime shape, host (Mac vs Start9;
|
||||
if Start9, s9pk vs plain container), model routing, data layer, interface, repo home. Where
|
||||
a call is genuinely contested (s9pk-vs-container often is), surface it with a recommendation
|
||||
rather than picking silently. The resulting placement table seeds `AGENTS.md`.
|
||||
- **Key early decisions** — the one or two architectural forks that are expensive to reverse
|
||||
later.
|
||||
- **First milestone** — the smallest first build step; it becomes the seed of
|
||||
`## Current state`.
|
||||
later. Capture each as a decided call: what was chosen, the alternative it beat, and the
|
||||
concrete condition that would reopen it. This is what lands in `AGENTS.md`'s "decisions
|
||||
already made" section (Phase 4), so the project never needs a separate decision-log file.
|
||||
- **First milestone** — the thinnest end-to-end slice that proves the core loop; it becomes
|
||||
the seed of `## Current state`. State its exit as **falsifiable substance** — a number or
|
||||
demonstrable behavior that could actually fail ("recap generated from a real 40-min call in
|
||||
under 2 minutes"), never a checkbox milestone ("set up the database"). If an exit can't
|
||||
fail, rewrite it until it can.
|
||||
|
||||
Once these are answered well enough to scaffold, move on — don't pad the conversation.
|
||||
|
||||
## Phase 2 — Brief + scaffolding plan (sign-off gate)
|
||||
## Phase 3 — Brief + scaffolding plan (sign-off gate)
|
||||
|
||||
Synthesize the workshop into two things and show them to the user **before creating
|
||||
anything on disk**:
|
||||
Synthesize the workshop and show the user **three things before creating anything on disk**:
|
||||
|
||||
1. **Project brief** — the seed of `AGENTS.md`: one-paragraph purpose, stack, non-goals, the
|
||||
first milestone.
|
||||
1. **Project brief** — the seed of `AGENTS.md`: one-paragraph purpose, the placement table,
|
||||
non-goals, the decided architectural calls, and the first milestone.
|
||||
2. **Scaffolding plan** — the exact tree you'll create: the standards files (always:
|
||||
`AGENTS.md` + `CLAUDE.md` symlink, `ROADMAP.md`, `README.md`, the canonical `.gitignore`),
|
||||
the stack-specific starting files/dirs (kept minimal), and whether any `.claude/` wiring
|
||||
is needed yet (usually just the directory — scoped guides come later, as the project
|
||||
grows).
|
||||
the stack-specific starting files/dirs (kept minimal), and whether any `.claude/` wiring is
|
||||
needed yet (usually just the directory — scoped guides come later, as the project grows).
|
||||
3. **Worth-building check** — now that the cost is visible, state it honestly: the build
|
||||
effort for the first milestone and beyond, plus the ongoing tax (every running service is a
|
||||
pet that needs updates, backups, and debugging when it breaks at a bad time). Land on
|
||||
**BUILD**, **PARK**, or **ADOPT**. PARK is a respectable outcome — re-capture the idea to
|
||||
`INBOX.md` with a one-line epitaph (tagged `parked`) so it isn't lost or re-workshopped from
|
||||
scratch, and stop here.
|
||||
|
||||
Get explicit sign-off. This is the last gate before disk.
|
||||
Get explicit sign-off on BUILD. This is the last gate before disk.
|
||||
|
||||
## Phase 3 — Scaffold (compliant from line one)
|
||||
## Phase 4 — Scaffold (compliant from line one)
|
||||
|
||||
Create `~/Projects/<name>/` and write, matching the standard exactly (`portability.md`):
|
||||
|
||||
- **`AGENTS.md`** — from the brief: purpose, `## Stack`, `## Commands` (stub the commands you
|
||||
expect, marked TODO where not yet runnable), `## Layout`, the **inbox-check line** tagged
|
||||
`(<name>)` (canonical wording in the standards repo's own `AGENTS.md`), and an initial
|
||||
**`## Current state`** ("Scaffolded <date>; next: <first milestone>").
|
||||
- **`AGENTS.md`** — from the brief: one-paragraph purpose; `## Stack` and a `## Placement`
|
||||
table (host, s9pk-vs-container, model routing, data layer, interface — from the placement
|
||||
workshop); `## Commands` (stub the commands you expect, marked TODO where not yet runnable);
|
||||
`## Layout`; a **`## Decisions`** section listing each architectural call already made, the
|
||||
alternative it beat, and the condition that would reopen it (this absorbs what a separate
|
||||
decision-log file would hold — keep it here, don't spawn an ADR file); the **sovereignty
|
||||
constraint stated plainly** if the project touches sensitive data (local inference only —
|
||||
never wire a frontier API to payload data); the **inbox-check line** tagged `(<name>)`
|
||||
(canonical wording in the standards repo's own `AGENTS.md`); and an initial **`## Current
|
||||
state`** ("Scaffolded <date>; next: <first milestone>").
|
||||
- **`CLAUDE.md`** — a *relative* symlink to `AGENTS.md`: run `ln -s AGENTS.md CLAUDE.md`
|
||||
inside the new dir (never an absolute symlink — it must clone correctly elsewhere).
|
||||
- **`ROADMAP.md`** — seed with the longer-term ideas and deferred non-goals from the
|
||||
workshop.
|
||||
- **`ROADMAP.md`** — seed with the phases beyond the first milestone (each with a falsifiable
|
||||
exit), plus the longer-term ideas and deferred non-goals from the workshop.
|
||||
- **`README.md`** — human-facing: what it is and how to run it (a stub is fine; mark TODOs).
|
||||
- **`.gitignore`** — the canonical block from `portability.md`'s "What git tracks"
|
||||
(deny-by-default `.claude/*` + the shared-wiring allow-list; `.env`/`.env.*`/`!.env.example`;
|
||||
@@ -83,35 +137,37 @@ Create `~/Projects/<name>/` and write, matching the standard exactly (`portabili
|
||||
- **Starting structure** — the minimal stack-specific skeleton from the plan; no more.
|
||||
|
||||
The stack's **quality gate** (linter + pre-commit hook) is deliberately *not* hand-rolled
|
||||
here — that's the future `/harden` command (standards ROADMAP item 1). Note it as a next
|
||||
step rather than improvising one.
|
||||
here — that's the future `/harden` command (standards ROADMAP item 1). Note it as a next step
|
||||
rather than improvising one.
|
||||
|
||||
Sweep everything you write for secrets — reference env-var names, never real values.
|
||||
|
||||
## Phase 4 — Publish (git + Gitea) and close the loop
|
||||
## Phase 5 — Publish (git + Gitea) and close the loop
|
||||
|
||||
- `git init`, stage, and make a single clear initial commit of the whole scaffold.
|
||||
- **Gitea publish gate** (reuse `retrofit-playbook.md` Part 4). Creating the repo on the
|
||||
user's self-hosted Gitea is a manual web-UI step — there is no API token to automate it.
|
||||
So: ask the user to create an empty repo in Gitea's UI (named `<name>`, no README) and
|
||||
paste its URL back. Then `git remote add origin <url>` and `git push -u origin <branch>`.
|
||||
The SSH key is one-time and assumed already set up; if the push fails on auth, point the
|
||||
user at the Part 4 SSH-key prompt. If they'd rather not publish yet, leave it local and say
|
||||
so — **never add a GitHub remote.**
|
||||
user's self-hosted Gitea is currently a manual web-UI step — there is no API automation yet
|
||||
(a `/new-project` Gitea-API enhancement is captured in `INBOX.md`). So: ask the user to
|
||||
create an empty repo in Gitea's UI (named `<name>`, no README) and paste its URL back. Then
|
||||
`git remote add origin <url>` and `git push -u origin <branch>`. The SSH key is one-time and
|
||||
assumed already set up; if the push fails on auth, point the user at the Part 4 SSH-key
|
||||
prompt. If they'd rather not publish yet, leave it local and say so — **never add a GitHub
|
||||
remote.**
|
||||
- **Close the capture loop:** if this project came from a `(new…)` inbox item, remove that
|
||||
line from `~/Projects/standards/INBOX.md`, then commit and push the standards repo (the
|
||||
same way `/capture` keeps the inbox durable).
|
||||
line from `~/Projects/standards/INBOX.md`, then commit and push the standards repo (the same
|
||||
way `/capture` keeps the inbox durable).
|
||||
|
||||
## Phase 5 — Verify compliance
|
||||
## Phase 6 — Verify compliance
|
||||
|
||||
Because you're the main thread, fan out **portability-checker** on the new repo to confirm
|
||||
it's compliant from line one — `AGENTS.md` canonical with a relative `CLAUDE.md` symlink,
|
||||
the deny-by-default `.gitignore`, no absolute in-repo symlinks. Relay only what needs a fix.
|
||||
it's compliant from line one — `AGENTS.md` canonical with a relative `CLAUDE.md` symlink, the
|
||||
deny-by-default `.gitignore`, no absolute in-repo symlinks. Relay only what needs a fix.
|
||||
|
||||
## Final report
|
||||
|
||||
Short summary: the new repo's path, what was scaffolded, commit + push status (and the
|
||||
Gitea URL, or that it's local-only), whether the `(new)` inbox item was cleared, and the
|
||||
first milestone to start on. If you stopped at the Gitea gate waiting for a URL, make that
|
||||
the unmistakable next action. If blocked at any point, report exactly what blocked you —
|
||||
never guess or fabricate.
|
||||
Short summary: the new repo's path, what was scaffolded, commit + push status (and the Gitea
|
||||
URL, or that it's local-only), whether the `(new)` inbox item was cleared, and the first
|
||||
milestone to start on. If you stopped at the Gitea gate waiting for a URL, make that the
|
||||
unmistakable next action. If you bailed at the form-factor gate or parked at the
|
||||
worth-building gate, say so plainly and where the idea was rerouted. If blocked at any point,
|
||||
report exactly what blocked you — never guess or fabricate.
|
||||
|
||||
Reference in New Issue
Block a user