Skip to content

Project foundation (skill)

Lay the foundation of a software project before implementation — intake, vision, requirements (PRD), research, blueprint with C4 views, architecture decision records, roadmap and issues, repository rules (AGENTS.md), owner approval — by running the UASK Engineering Hub playbook mgmt.project-foundation with its templates.

Download SKILL.md — the skill, as in the repository.

When to use

Use when the owner asks to start a project properly, write a vision, PRD or blueprint, re-found or rewrite an existing product, or begin large new work on a product that has no foundation documents.

  • Carries out the playbook Project foundation (written for version 0.4.3).
  • Source: skills/project-foundation/SKILL.md · licence CC-BY-4.0.
  • Works with: Any coding agent that reads Markdown and uses git. The GitHub CLI (gh) is used for issues and milestones when available.
  • To install skills: Get started with the Hub in your project.

Project foundation

This skill runs the playbook mgmt.project-foundation. The playbook holds the rules, the stages and their entry and exit criteria; this skill only says how an agent carries them out. Where the two seem to differ, follow the playbook and report the difference.

Before you start

  1. Find the Hub. In a project that vendors it, read .uask/hub/; otherwise read the UASK Engineering Hub repository the owner points to. Note the release or commit you read; it goes into the foundation issue and into the project’s AGENTS.md (mgmt.project-foundation#R11).
  2. Read the playbook (content/playbooks/project-foundation.md) in full, then arch.adr (content/core/architecture/adr.md) and arch.c4-model (content/core/architecture/c4-model.md).
  3. You are the lead developer. You draft, research, propose and verify; the owner approves, accepts and decides scope (mgmt.project-foundation#R9). Read the project’s existing AGENTS.md, if there is one, for anything stricter.
  4. If your environment does not list this skill by name — a vendored copy under .uask/hub/skills/ is not always registered — open its SKILL.md and follow it as written; say so in the run record or the issue.

Steps

Run the stages in order (mgmt.project-foundation#R2). Close a stage only when its exit criteria in the playbook are met (mgmt.project-foundation#R3). Each artefact starts as a copy of its template, keeps the template’s front matter and the sections not marked “Optional”, and goes to the path below or to the path recorded at intake (mgmt.project-foundation#R4).

Stage Copy To
2 Vision templates/vision.md project/VISION.md
3 Requirements templates/prd.md project/PRD.md
5 Blueprint templates/blueprint.md project/BLUEPRINT.md
6 Decisions templates/adr.md project/decisions/NNNN-<slug>.md
7 Roadmap templates/roadmap.md project/ROADMAP.md
8 Bootstrap templates/agents.md AGENTS.md
1 Intake, without a tracker templates/run-record.md project/RUN.md
1 Intake, from a client’s request templates/client-brief.md intake/CB-NNN.md, in a private folder
  1. Intake. Open the foundation issue: the owner’s brief verbatim, what is already known, the roles, the tailoring and the questions (mgmt.project-foundation#R1). Create branch docs/<issue>-foundation. Ask the owner all blocking questions in one message, then wait for the tailoring to be confirmed — this is the only stop before the gate. Propose the governance tier (mgmt.governance-tiers) with your reasons; the owner decides it. With no tracker or repository, keep the brief and the tailoring in the run record instead of an issue, and list stage 8 as skipped with the reason. When the work starts as a client’s request, first run the step “From a request to an estimate and G0” of the playbook (mgmt.project-foundation#R19, mgmt.project-foundation#R20); do not write to the client.
  2. Vision. Fill project/VISION.md from the brief and the answers. Ask the owner to confirm the statement and the non-goals in the issue; continue with requirements meanwhile.
  3. Requirements. Fill project/PRD.md. Give every scenario, requirement and acceptance criterion an id (mgmt.project-foundation#R5) and name the vision outcome each scenario serves; check that no outcome is left unserved. Add the operability targets (mgmt.project-foundation#R13). If the work replaces or rebuilds a running system, walk the checklist “External interfaces and environment” of the PRD template with the people who know the system and the hosting, and turn each entry into a requirement, a criterion or a dropped item (mgmt.project-foundation#R12). For each acceptance criterion write the method, the environment, the expected result and who performs it, then ask whether it can really be performed in that environment (mgmt.project-foundation#R14). For a product that already exists, show what works in one parity table instead of many requirements.
  4. Research. Write one note per blocking question in research/. Run independent questions in parallel (subagents or separate sessions) and keep their output in files. Compare at least two options with sources and access dates, measurements or spikes (mgmt.project-foundation#R8); a spike is named in its note and is not merged as product code (mgmt.project-foundation#R10). Where earlier reports exist, write research/index.md that links them and says which blocking question each answers, instead of copying.
  5. Blueprint. Fill project/BLUEPRINT.md: context and container views as arch.c4-model describes (mgmt.project-foundation#R7), stack, risks, implementation sequence; for a replacement of a running system also the cutover and rollback sequence. Mark each significant choice [ADR-NNNN], or [ADR-candidate Dn] while it has no number (mgmt.project-foundation#R6). Ask a reviewer who did not write it — the technical lead or a second agent given only the files — to look for gaps and risks.
  6. Decisions. Write one ADR per mark, status proposed, following arch.adr, and replace every [ADR-candidate Dn] mark with the link. For an existing product, also record the decisions already in force: status stays proposed, the owner decision section names the date and the source of the earlier decision, and date: is the day you write the record (mgmt.project-foundation#R9).
  7. Roadmap and issues. Fill project/ROADMAP.md; create the milestones and one issue per deliverable, each citing the requirement ids it serves (with gh issue create and gh api for milestones when the tracker is GitHub). Without a tracker, give each deliverable an id in the roadmap and write a brief file.
  8. Repository bootstrap. Fill AGENTS.md; add CLAUDE.md with the single line @AGENTS.md plus Claude-only notes; make CI run one check script; add a pull request template. On a live system take and verify a backup first (ops.backups).
  9. Owner approval gate. Open the foundation pull request (closing the foundation issue) with: the artefacts, one list of decisions needed from the owner, assumptions and main risks. Leave statuses at review and proposed. When the owner asks for a change, go back to that stage and carry the change forward to every later artefact. Without a pull request, ask the owner to set status: approved with the date in each artefact.

Before you report a stage as closed

  • Every exit criterion of the stage in the playbook is met; say how you checked each one.
  • Run python3 .uask/hub/tools/check_artifacts.py . (in the Hub repository, tools/check_artifacts.py) and fix every FAIL line: template front matter and sections, unique and resolving ids, ADR files. A WARN line is yours to judge. Add --require vision,prd,blueprint to make a missing artefact an error.
  • What the tool cannot see you check yourself, with a small script or by hand: each requirement is covered by the blueprint and the roadmap, each acceptance criterion can be performed where it says, each number agrees with its source.
  • A project that writes in its own language keeps the template’s section headings in English, because the tool matches them.
  • Technical claims carry a source, a measurement or a check, or are marked as assumptions.

Report

After each stage, at most five lines: the stage, the artefact paths, exit criteria met or not, questions for the owner. Details belong in the artefacts and the pull request, not in chat.