---
name: aide-manifest
description: >-
  Draft or refresh the project's .aide/project.yaml manifest — what the
  project IS: stack, dependencies, deployment, logging, statistics,
  reports, docs. Drafts from the codebase, ASKS about what it cannot
  derive, never guesses.
  Use when: setting up Aide in a project, the manifest is stale, an
  analysis needs project context that is missing.
  Do NOT use for: per-user settings (.aide/config), creating specs
  (use aide-create), analyzing a task (use aide-analyze).
argument-hint: "[project path, defaults to the current project]"
effort: medium
---

Give the project a machine-readable identity card: `.aide/project.yaml`
in the project root. It is TEAM knowledge and belongs in git — unlike
`.aide/config`, which is personal.

**Input:** $ARGUMENTS (a project path; default: the current project root)

## Workflow

The steps below are this skill's own, inside the queue's `manifest` step.
Mark each one in the log, so a reader can follow the run: when it
starts, write one line `--- Step N of X: <title> — started`, and when
it ends, one line `--- Step N of X: <title> — done`. A step that ends
the run early says `— stopped: <why>` in place of `— done`, and one that does not apply to this run `— skipped: <why>`.

### Step 1 of 5: Establish the state

First write `--- Step 1 of 5: Establish the state — started`, and when this step ends, `--- Step 1 of 5: Establish the state — done`.


- Project root: the git toplevel of the argument or of the current
  directory
- If `.aide/project.yaml` exists: this is a REFRESH — read it, and show
  the user a diff of every change you propose before writing
- Otherwise: this is a DRAFT — start from
  `references/project.yaml` (the annotated example)

### Step 2 of 5: Derive what the codebase can tell

First write `--- Step 2 of 5: Derive what the codebase can tell — started`, and when this step ends, `--- Step 2 of 5: Derive what the codebase can tell — done`.


Read the project and fill in what is derivable:

- **stack:** build files (package.json, pom.xml, go.mod, ...), language
  mix, frameworks
- **deployment:** deploy scripts/commands, CI workflows, host config
  files (wrangler.toml, fly.toml, Dockerfile, ...). Those files often
  reveal that the host builds every branch, but rarely the exact
  address one is served on — see `deployment.preview` in Step 3
- **dependencies:** external services the code talks to (API clients,
  connection strings' KINDS — never secrets)
- **docs:** README and doc folders that exist

### Step 3 of 5: Ask about what it cannot

First write `--- Step 3 of 5: Ask about what it cannot — started`, and when this step ends, `--- Step 3 of 5: Ask about what it cannot — done`.


Log locations, statistics dashboards, report links (e.g. a Claude
artifact regenerated by a routine) are not in the code. Neither is
`deployment.preview`: where ONE branch can be tried, as a template with
a literal `{branch}` in it (`https://{branch}.example.pages.dev`). Ask
for it only when the host builds per branch, and leave it out
otherwise — a project without per-branch previews has no such address,
and the dashboard shows nothing rather than a link that 404s. Ask the
user for all of these — one compact question round, multiple-choice
where possible.
NEVER guess a URL or a location. Leave unanswered keys out rather than
inventing values.

### Step 4 of 5: Write and stamp

First write `--- Step 4 of 5: Write and stamp — started`, and when this step ends, `--- Step 4 of 5: Write and stamp — done`.


- Write `.aide/project.yaml` with `generated: <today>` (the staleness
  signal)
- Keep it SHORT: links over prose, no essays — if a value needs a
  paragraph, it belongs in the project's docs with a link here
- The file is committable: `git add .aide/project.yaml` (in a fresh
  project, verify `.aide/` is not swallowed by an ignore rule — only
  `.aide/config` should be ignored)
- **Leave a `worktreeLinks:` key exactly as found — never propose one,
  never remove one.** It is the dashboard's to write, and it
  names the gitignored paths a headless run symlinks into its worktree.
  Dropping it on a refresh breaks every OTHER machine's runs the next
  time they pull, while this one carries on working — a manifest is
  committed, and this key is the one thing in it that a refresh has no
  way to derive back
- **Leave an `AIDE_TEST_CMD:` key exactly as found — never propose one,
  never remove one.** It is the project's test command, the only one a
  run reads, set from the dashboard's Settings

### Step 5 of 5: Confirm

First write `--- Step 5 of 5: Confirm — started`, and when this step ends, `--- Step 5 of 5: Confirm — done`.


```text
Manifest written: .aide/project.yaml (draft)

Derived: stack, deployment, docs
From you: logging, statistics, reports
Left out (unknown): dependencies

Refresh later with /aide-manifest — consumers: /aide-analyze reads it
for project context; the aide dashboard renders it.
```

IMPORTANT:
- Never write secrets (tokens, connection strings) into the manifest
- Never guess facts you could not derive — ask or omit
- Code blocks ALWAYS end with just ` ``` `