--- name: project-design description: > Assembles a complete planning package for software projects across two phases: product design (whitepaper, long/short horizons, agent instructions) in Phase A, then an engineering handbook, CI/CD plan, agent loop, and a bootstrap folder of GitHub artifacts (LICENSE, labels, branch protection, workflows, templates) in Phase B once the repo exists. Uses adaptive brainstorming via an exploration map rather than a linear interview. Trigger when the operator wants to plan, design, spec, or bootstrap a software project — including new ideas, existing codebases needing structure, CLAUDE.md generation, repo bootstrap, CI setup, or updates to an existing `{project}-design/` folder. Triggers on English and Swedish phrasing equally. --- # Project Design Skill Creates a complete planning package for software projects: product design documents in Phase A, operationalization documents plus a bootstrap folder in Phase B, ongoing revisions in Phase C. Works for CLI tools, web/SaaS apps, AI agent systems, libraries, and so on. **Platform assumption:** GitHub. All repo artifacts are generated in GitHub format (Actions YAML, `gh`-compatible JSON). Deliberate choice for simplicity. --- ## Output language policy This skill file and all `references/*` files are written in English. They are the agent's internal source-of-truth and must remain in one language for consistency. Output to the operator (conversational replies, generated document content, examples, commit message drafts, etc.) follows this rule: 1. If the operator has stated a preferred language (in preferences, in memory, or at any point in the conversation), use that language. 2. Otherwise, default to English. Exception: code-adjacent artifacts that are committed to the repository (LICENSE, CONTRIBUTING, SECURITY, README, design docs in `{project}-design/`, source comments, commit messages) are always written in English, regardless of the conversation language. The repository is a public-facing artifact and English is the lingua franca of open source. This is non-negotiable. --- ## Identity neutrality in generated documents All documents generated by this skill (whitepaper, horizons, agent instructions, handbook, CI/CD plan, agent loop, bootstrap artifacts) must use identity-neutral placeholders by default: | Reference type | Placeholder | |---|---| | First/second person (the project's maintainer) | `operator` | | Third-person example actors (showing namespace distinctions, conflicts, plugin authors) | `alice` and `bob` | | Organization handle in examples | `acme-org` or similar non-personal placeholder | | Email addresses in examples | `operator@example.com`, `alice@example.com`, etc. | | Domain names in examples | `example.com` and subdomains | Concrete identifiers (real GitHub handles, real org names, real emails, real domains) appear in generated documents ONLY when the operator has explicitly confirmed during the Phase A → Phase B confidentiality checklist that they may be used. Defaults are placeholders. **The agent must not infer disclosure permission from memory or conversation context.** If the operator has mentioned identifiers earlier (handles, emails, domains, related projects), this is conversational context, not consent to commit those identifiers into public artifacts. Explicit confirmation is required. --- ## Open questions tracking The agent maintains a running list of open questions throughout the session. The operator should not have to backtrack ten prompts to verify whether a question was missed. The agent is permitted to interpret implicit OK in many situations — the operator's established patterns, consistent preferences, and prior approvals make many decisions predictable. This skill encourages that interpretation as the default behavior, because it keeps the flow efficient. But it must be balanced against the cost of unanswered questions piling up silently. ### Categories where implicit OK MAY be assumed The agent may proceed without explicit confirmation when: - The decision is aesthetic, formatting, or stylistic, and the operator has shown a consistent preference pattern - The decision is a minor sub-detail consistent with a major decision the operator has already approved - The decision falls within an area the operator has delegated authority on (implementation specifics, naming conventions within established schemes, etc.) - The decision is reversible and low-cost to revisit - The operator's reply, while not addressing the question word-for-word, clearly implies the answer through context ### Categories where implicit OK MUST NOT be assumed The agent must ask explicitly when: - License, intellectual property, or other legally consequential choices - Security model decisions (sandboxing, trust boundaries, disclosure channels) - Repository namespace, visibility, and identity disclosures - Branch protection, CI gating, or deployment rules - Anything where downstream code or configuration generation depends materially on the answer - Anything the operator has previously flagged as "I'll return to this", "let me think", or similar deferral - Anything that touches the confidentiality checklist - Anything that requires the operator's legal, financial, or personal judgment ### Behavior when an open question is identified When the agent identifies a question in the "must not assume" category that the operator has not answered: 1. Add it to the running open questions list 2. Present it explicitly at the next natural break point — before any generation that depends on the answer 3. Use a clearly visible format (numbered list under an "Open questions" heading) ### Milestone audit Before any major batch generation (Phase A package, Phase B package, multi-file deliveries that span hours of work), the agent performs a brief audit: 1. Review the session for questions raised by the agent that the operator did not answer 2. Filter to those in the "must not assume implicit OK" category 3. Present them explicitly with a framing line like: "These questions remain open from earlier — resolve before I generate the next batch." The audit removes the burden on the operator to backtrack through the conversation hunting for unanswered questions. ### Mid-reply partial-answer handling When the operator's reply addresses some but not all questions in the agent's previous message, the agent does not silently drop the unanswered ones if they fall in the "must not assume" category. They are re-raised in the next reply with a brief reminder: "Still open from previous: [N], [N+1]." The agent does not nag — once flagged twice in succession, if the operator continues not to answer, the agent treats it as a signal the operator is deferring and parks the question with an explicit "parked" annotation. It is then the operator's responsibility to un-park. --- ## Phases The skill runs in two main phases with an operator-driven intermediate step, plus an iteration mode. | Phase | Content | State at handoff | |-------|---------|------------------| | A — Product design | Brainstorming + 00-index, 01-whitepaper, 02-long-horizon, 03-short-horizon, 04-agent-instructions | Operator has created the repo | | B — Operationalization | Silent assumptions from A presented as recommendations, possible revision of 03–04, then 05–07 + bootstrap | Package complete | | C(N) — Iterations | Detected on return to an existing `{project}-design/`. Adaptive revision of affected documents. | As needed | --- ## Phase A — Product design ### Brainstorming via the exploration map The brainstorming is not a linear checklist. It is adaptive mapping according to `references/exploration-map.md` (what to explore) and `references/brainstorming-techniques.md` (how the exploration happens). Areas are covered in approximate priority order for the project type — critical tier 1 areas first, tier 2 thereafter, tier 3 if relevant. Return visits to earlier areas are allowed when new insights surface; the map is a graph, not a sequence. **Three input modes** (calibrated per area): - *Too little info or uncertain* → open question + concrete example - *Right amount of info* → confirm briefly and move on - *Lots of info with gaps* → point out shortcomings, propose additions/changes with motivation **Core rule:** justified criticism serves the result, not the operator's comfort. See `brainstorming-techniques.md` for anti-patterns (mirroring, over-interpretation of priority answers, stacking of assumptions). ### Silent assessment Most operationalization questions — strictness level, branch strategy, release cadence, distribution channels, need for CoC/SECURITY — are *not* asked explicitly in Phase A. They are assessed silently from the brainstorming output and logged internally. At the Phase A → Phase B handoff, they are presented as recommendations with motivation, and the operator approves or adjusts. Assumptions that underpin Phase B are *preserved* in `01-whitepaper.md` under a short "Assumptions for Phase B" section, so they survive a session change. See `references/silent-assessment.md`. ### Explicit decisions in Phase A (not deferred to silent assessment) The following decisions must be raised explicitly with the operator at the appropriate point in Phase A. They cannot be silently assumed and confirmed later — they shape what Phase B can generate at all, or what 03 and 04 even look like. | Decision | When raised | Why explicit | |---|---|---| | **Implementation mode** | Phase A, *before* 03 and 04 are written | Shapes the detail level of 03 and 04, the granularity rule for the implementing agent, and the merge strategy downstream. Defaulting silently leads to rework. | | **License** | Late in Phase A, before handoff | Affects every committed file; cannot be defaulted without operator awareness. License choice has legal and ecosystem consequences the operator must own. | This list is short by design. Add to it only when a decision genuinely cannot be made silently without risk of significant Phase B rework. #### Implementation mode Two modes, chosen by the operator. Both are valid; the choice depends on how the operator wants to work with the implementing agent. **`iterative`** — design co-evolves with implementation. - The design package (00–04) is the starting point but expected to evolve as implementation reveals new realities. - Documents in `{project}-design/` are mutable during the build. - 03-short-horizon is grain-of-salt — high-level steps, adjustments expected. - 04-agent-instructions delegates to 05/06/07 and trusts the implementer to make local design decisions within those rules. - Phase C revisions happen often, sometimes per implementation milestone. - Commit granularity is encouraged for a readable git log but not strict — PR-level Conventional Commits + squash-merge works for release-please because each PR is a single logical unit of work. - Default merge strategy: squash. - The operator stays close to the implementer and reviews as work unfolds. **`spec-first`** — design is locked at the end of Phase A and is the source of truth through the build. - 03-short-horizon is highly detailed — every step pre-approved, executed verbatim. - 04-agent-instructions includes an explicit narration rule (the implementer announces what it is working on at each step) so the operator can monitor long autonomous runs without wondering whether progress has stalled. - 04-agent-instructions includes an explicit commit-granularity rule (one logical change per commit, no batching). - Phase C revisions happen only at genuine scope shifts. - Commit granularity is strict 1:1 with pre-approved steps. - Default merge strategy: rebase-merge — squash would collapse granular commits and break the per-commit mapping release-please relies on for changelog entries and version-bump detection. - The operator can run the implementer more autonomously (overnight, via push notifications, etc.). **Default suggestion:** `iterative` for solo learning projects and exploratory builds; `spec-first` when the operator explicitly wants to lock the design, when release-please is in use with rich changelog expectations, or when autonomous overnight runs are planned. The agent should suggest a default with motivation and let the operator confirm or override. ### Acceptance criterion Phase A concludes when: - All tier 1 areas for the project type are covered - No unresolved tier 2 areas of significance remain - The implementation mode has been explicitly decided (before 03 and 04 were written) - The license has been explicitly decided - The operator has nothing to add or change in any area The agent signals via a short summary: "I judge Phase A to be complete — anything you want to add before I generate the package?" ### Output Files generated to `{project}-design/`: - `00-index.md` — overview - `01-whitepaper.md` — product description + assumptions for Phase B - `02-long-horizon.md` — coarse plan (phases, milestones) - `03-short-horizon.md` — detail plan, nearest phase. *Marked "may be revised at Phase B start"* - `04-agent-instructions.md` — agent instructions. *Marked "may be revised at Phase B start"* The bootstrap folder is *not* generated in Phase A. ### Closing Phase A The agent asks the operator to create the repo and return with written confirmation. Written "done" suffices — no hard verification. It does not matter how the repo was created. That starts Phase B. Use `present_files` to deliver Phase A files. This is non-negotiable. --- ## Phase A → Phase B confidentiality checklist Before Phase B generates any artifact that will be committed to the repository, the agent **must** clarify the following with the operator. Skipping this step or guessing answers is forbidden. ### What must be clarified 1. **Repo namespace**: organization or personal account? What is the exact handle? 2. **Repo visibility**: private or public? If public, from which version onward? 3. **Operator identifiers in committed artifacts**: - GitHub handle: use as-is / placeholder / avoid entirely? - Email addresses: which addresses, for what purposes (maintainer contact in package metadata, security disclosure, etc.)? - Other public IDs (websites, social handles, etc.)? 4. **Information from conversation context**: - Which related projects may be referenced explicitly in committed documents? - Which personal details from memory or earlier conversation must NOT be included (handles on other platforms, machine names, partner names, location, employer, hobbies unrelated to the project, etc.)? 5. **Regulatory considerations**: any GDPR, HIPAA, export-control, or similar requirements that affect what can be in the repo? ### What the agent must NOT do - Guess based on patterns observed in earlier conversation - Infer permission from memory entries without explicit confirmation - Assume that because the operator mentioned an identifier in conversation, it may be committed to a repository ### When an output is blocked at any phase If a tool call, document generation, or chat reply is blocked or refused for what appears to be a confidentiality reason at any point during the skill's execution: 1. **STOP** all further generation immediately. 2. Inform the operator that an output was blocked and that the agent does not know the exact trigger. 3. Re-open the confidentiality checklist explicitly. 4. Resume only when the operator has clarified what may and may not be shared. The agent does not pattern-match the failure and continue. It treats the block as a signal to re-establish ground truth with the operator. --- ## Phase B — Operationalization Starts *only* after the operator's written confirmation that the repo exists AND after the confidentiality checklist has been worked through. ### Step 1 — Present silent assumptions Assumptions from Phase A are presented as concrete recommendations with motivation, not as questions. The operator approves or adjusts. Format per recommendation: > "Assumption: [X]. Motivation: [Y]. Approve or adjust?" Areas typically covered: strictness level (`solo`/`solo+contrib`/`team`), branch strategy, release cadence, distribution, CoC/SECURITY needs. License is NOT in this step — it was decided explicitly in Phase A. ### Step 2 — Revise 03 and 04 if necessary 03-short-horizon and 04-agent-instructions were created in Phase A before repo context existed. Re-examine whether anything in them is outdated given the operationalization decisions. List concrete revisions; wait for approval before writing. ### Step 3 — Generate 05–07 + bootstrap - `05-engineering-handbook.md` — license, branch, commits, PR, release, maintenance - `06-ci-cd-plan.md` — workflows, environments, deploy, rollback, observability - `07-agent-loop.md` — loop cadence, reporting format, escalation, termination - `bootstrap/` folder with importable repo artifacts (see below) ### Bootstrap folder ``` bootstrap/ ├── LICENSE (always) ├── README.md (always, skeleton) ├── IMPORT.md (always, gh commands for import) ├── .gitignore (always, stack-specific) ├── .editorconfig (always) ├── CONTRIBUTING.md (always; length scales) ├── CODE_OF_CONDUCT.md (if public or team) ├── SECURITY.md (if public or team) └── .github/ ├── labels.json ├── branch-protection.json ├── repo-settings.json ├── dependabot.yml ├── PULL_REQUEST_TEMPLATE.md ├── ISSUE_TEMPLATE/ │ ├── bug_report.yml │ ├── feature_request.yml │ └── config.yml └── workflows/ ├── ci.yml └── release.yml (if release cadence requires it) ``` Stack-specific additions (Go: `.golangci.yml` + optional `goreleaser.yaml`; JS/TS: `commitlint.config.cjs` + `.eslintrc.json` + `.prettierrc`; Python: `pyproject.toml` + `ruff.toml`; Rust: `rustfmt.toml` + `clippy.toml` + optional `cargo-dist.toml`; Shell: `.shellcheckrc`). See `references/bootstrap-artifacts.md` and `references/ci-cd-templates.md`. ### Artifact generation mode There are two ways the bootstrap artifacts (LICENSE, `.gitignore`, CI workflows, issue/PR templates, etc.) can reach the repo. Ask which the operator wants, or follow a recorded preference. - **Delivered (default):** Phase B generates the `bootstrap/` folder as importable files, delivered via `present_files`. Best when a human operator bootstraps the repo manually before the implementing agent starts. - **Specified (implementer-generated):** when the implementing agent is an AI that bootstraps the repo itself — typical in `spec-first`, AI-driven builds — the operator may prefer that Phase B generate ONLY the numbered docs. In that case 05–07 must specify each artifact in enough detail that the implementer generates it in place. This keeps a single source of truth in the numbered docs and avoids handing the operator a separate payload to read, sort, and reconcile. The `bootstrap/` folder is omitted; its contents are specified within 05–07. ### Delivery Everything is delivered with `present_files`. Non-negotiable. --- ## Phase C(N) — Iteration mode ### Detection Activated when the skill runs and a `{project}-design/` folder already exists from a prior run. If the context is unclear (multiple projects, or unclear which is active), ask briefly which one applies. ### Step 1 — Read what exists Read all files 00–07 (or those present). Internally list what is established and what is missing or outdated based on the operator's new input. ### Step 2 — Assess scope delta Identify whether scope changes (new contributors, public/private flip, new stack, new release cadence, larger or smaller project than planned) justify level adjustments. Provide recommendations both upward and downward — the risk of loop creep must be actively counteracted. List the documents and artifacts affected. ### Step 3 — Adaptive revision Wait for approval before any change is written. Revisions can touch one, several, or all documents. Bootstrap artifacts are regenerated on relevant operationalization changes. --- ## Strictness levels (reference) Many choices scale with the project's character. Three levels: | Level | Trigger | |-------|---------| | `solo` | Only the operator + AI, no external contributors | | `solo+contrib` | Operator primary but open to PRs | | `team` | Multiple regular contributors | Constant regardless of level: LICENSE, README, .gitignore, .editorconfig, Conventional Commits, branch strategy (even simple), release process (even simple), CI workflow, Dependabot, branch protection on `main` (soft on solo, hard on team), all seven documents 01–07. Scales with level: reviewer requirements (0/1/2), `CONTRIBUTING.md` size, presence of `CODE_OF_CONDUCT.md` and `SECURITY.md`, issue templates, code review policy, agent loop cadence. --- ## Project size calibration | Size | 01 | 02 | 03 | 04 | 05 | 06 | 07 | |------|----|----|----|----|----|----|----| | Small | 1–2 pages | 2–4 phases | 5–10 steps | 1 agent | Short | Short | Per step, chat | | Medium | 2–4 pages | 4–6 phases | 10–20 steps | 1–3 agents | Standard | Standard | Per branch, PR | | Large | 4–8 pages | 6+ phases | Sprint plans | Multi-agent | Extensive | Extensive | Per step + daily | --- ## Handling existing partial files If files from a prior run in the same session already exist in the `{project}-design/` folder: verify against current choices by reading them, report explicitly to the operator what was found, and ask whether to keep, revise, or rewrite. Do not silently retain. --- ## Important principles - **Design choices must be motivated** — not just what was chosen, but why. - **Concrete over abstract** — avoid vague phrasings like "handle errors appropriately". - **Agent instructions must be self-contained** — point to 05/06/07 from 04, do not duplicate. - **Iterate rather than block** — produce a first draft and refine with feedback. - **Right-sized DevOps** — the routine (commits, CI, releases, branch protection, Dependabot) is always present, even solo and even in docs-only repos: it builds ecosystem fluency and muscle memory and keeps the build legible and traceable. What scales is its *weight, not its presence* — minimize the flow to the minimum overhead the work needs. The failure mode to avoid is overhead, not the routine: CI that blocks on checks it need not, or measures what does not matter here. Minimize friction; never skip the routine. - **Bootstrap is not design** — `bootstrap/` contains importable files, not descriptions. Design decisions belong in 05/06; the artifacts in bootstrap are the operationalization. - **Artifact generation mode** — bootstrap artifacts are either delivered as an importable `bootstrap/` folder (default) or specified within 05–07 for an AI implementer to generate in place (preferred for `spec-first`, AI-driven builds). See § Phase B — Artifact generation mode. - **Result before agreement** — justified criticism serves the product. Mirroring and appeasement are not technique. See `brainstorming-techniques.md` § Anti-patterns. - **Identity neutrality by default** — see § Identity neutrality in generated documents. Concrete identifiers only after explicit operator confirmation. - **No guessing on confidentiality** — see § Phase A → Phase B confidentiality checklist. If unclear, ask. If blocked, stop and re-establish. - **Track open questions, audit at milestones** — see § Open questions tracking. Default to interpreting implicit OK; escalate to explicit ask when consequences are material; audit before major deliveries.