Project Design

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.

---

Runtime mode-selector (direktor context)

This skill is one of three separate skills direktor self-assesses between at runtime — alfred (assistance/counsel/memory), direktor (orchestration/dispatch), and project-design (this skill) — kept separate rather than merged into one superskill, so the mode-classifier stays additive (see the direktor skill § Runtime Mode-Selector). project-design is the DESIGN mode: direktor switches into it for planning/spec/ bootstrap work and switches out of it once that work is parked or handed off.

Entering or leaving this skill counts as a new thread boundary for direktor, which re-assesses park-vs-continue there, weighted by importance (refinement leans park; refactor/acute/bottleneck work leans continue-now; unclear cases are asked). When a design item is parked mid-work, its heading carries a [design] mode-tag (e.g. [design] fleet-GitOps epics) so a later pickup knows to reactivate this skill.

This is a pointer for orchestration context only — it does not change this skill's own Phase A/B/C mechanics below.

---

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.

1. 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

1. 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

1. Filter to those in the "must not assume implicit OK" category
2. 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, delivery model, 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.

Delivery model

One silently-assessed property deserves a name because it reshapes Phase B more than the others: the delivery model — how the project ships and runs.

• Artifact — a versioned thing someone installs or imports (library, CLI, binary,

package). Release means a tagged version; CI lints, tests, and builds; SemVer and a changelog apply.

• Deployment — a running system someone uses (website, service, infrastructure).

Release means a verified deploy, not a tag; CI renders/builds then deploys then runs a smoke or health gate; versioning is usually absent — the live system is the version.

Delivery model and project size together right-size the package: they set its weight, never its presence. A small deployment project still gets docs, CI, and the routine — at the lowest overhead that fits (see § Important principles, Right-sized DevOps). The model also selects which release and CI pattern Phase B reaches for; see references/engineering-handbook-templates.md § Release process and references/ci-cd-templates.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.)?

1. 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 na

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alfred-intelligence
• Source: alfred-intelligence/project-design-skill
• License: MIT
• Homepage: https://alfred-intelligence.github.io/project-design-skill/

Install and usage instructions live in the source repository linked above.