Bootstrap the Project Spec

Give an agent a repeatable procedure to walk an existing repository and its documentation, synthesize a base project spec, and apply it to Flownix as the project spec plus a set of doc nodes. Prerequisite: read flownix-basics for the hierarchy, statuses, spec mode and the "ticket is memory" rule.

When to use

• The project's spec (in the project config / on the project node) is empty or clearly stale.
• spec_mode is strict and there is nothing yet to apply deltas against.
• The project was just connected (flownix-init) to a repository that already has code and docs — the spec needs to catch up with reality, not be invented from scratch.

Workflow

0. Load project context

Read the project config (.flownix, or the older .ai-flow) from the working directory to get project_id/org_id:

cat .flownix 2>/dev/null || cat .ai-flow

Parse the YAML and use project_id/org_id in all subsequent calls. If the config is missing, run flownix-init first.

Then call get_project_policy — the mode could have been switched to strict after init, and the value cached in the project config may be stale. The returned spec_mode governs step 4.

1. Inventory the sources

Read cheap, high-signal sources first; open code only when the manifests/docs don't already answer the question. Suggested order:

1. README.md and docs/** (including any ADRs) at the repo root.
2. CHANGELOG / release notes.
3. Language/package manifests: go.work, go.mod (per module), package.json (per app).
4. Service layout: services/** and any top-level app dirs (web, admin, landing, …).
5. External contracts: proto/** plus buf.yaml/buf.gen.yaml.
6. migrations/** (schema history, per service).
7. Deployment: k3s/** (or other manifests), Dockerfile*, docker-compose.yml.
8. CI workflows (.github/workflows/** or equivalent) and the root Makefile.

For each, note explicitly what exists and what doesn't — a missing category is a fact worth recording, not something to skip silently. Do not copy source code verbatim into the spec; summarize structure and contracts, not implementation detail.

2. Check what already exists

Before creating anything, search — a doc that already covers a topic should be updated, not duplicated:

list_docs({ project_id })
rag_query({ project_id, query: "<topic of the section you're about to write>", k: 5 })

Run this per planned section (architecture, domain model, contracts, conventions, …). A hit means: update that doc. No hit means: create one. Treat an empty rag_query result together with a list_docs scan as the confirmation, not either alone — the index can lag a fresh write by a few seconds.

3. Synthesize

Use this skeleton for the project spec and for each doc-node section. Keep every claim tied to a source found in step 1; anything you cannot point at goes in Open questions & gaps instead of being stated as fact.

## Purpose & scope
What the product/repo is for, and what is explicitly out of scope.

## Stack & versions
Languages, frameworks, runtimes, and their versions as declared in manifests.

## Architecture
Services/apps, their boundaries, how they talk to each other (transport), and what they
store data in.

## Domain model & vocabulary
Core entities and the terms the codebase/docs use for them.

## External contracts
REST/HTTP APIs, proto/gRPC services, MCP tools — what's exposed and to whom.

## Conventions
Build, test, migration, and release process as actually practiced (CI workflows, Makefile
targets, scripts).

## Open questions & gaps
Anything asserted above without a source, anything the inventory expected but didn't find,
and anything that looked inconsistent across sources.

3b. Write the behaviour parts in the standard format

The skeleton above is an inventory: stack, architecture, vocabulary. Those sections stay descriptive prose under ## Purpose and that is fine — they describe what exists, not what the system promises.

External contracts are different: they are behaviour, and behaviour is recorded in the OpenSpec format — the only accepted way to do it here. ## Purpose, ### Requirement: <name> with a RFC 2119 keyword (SHALL/MUST/SHOULD/MAY), #### Scenario: with GIVEN/WHEN/THEN steps. Freeform prose describing a contract is a defect, not a style choice.

The format and the whole authoring procedure live in flownix-write-spec — read it and follow it. It is not restated here on purpose: the same block used to sit in three skills, and three copies drift.

A bootstrapped document mixing both is expected and allowed. validate_spec will report the descriptive sections as issues — those are inherited issues: in spec_mode=strict they come back as warnings and never block a delta. Only new issues block. Do not rewrite the inventory into requirements to silence them.

4. Apply

• Update the project spec (the spec field surfaced via the project config / project node) with the synthesized content.
• Create or update doc nodes per section (create_doc_node for new ones), each bound to the components it describes — create_doc_node({ ..., components: ["AF-COMP-3"] }) or set_node_components afterwards. Several components per doc are normal: an architecture section describing gateway and core-service belongs to both. If the project has no components yet, run map-components first — the inventory in step 1 is exactly the input it needs, so do both in one pass rather than leaving the docs unbound.
• Branch on spec_mode (from step 0):
  • strict — an existing doc can only change through propose_doc_delta (full new body, source node = this task) followed by apply_doc_delta. Never call update_node_content on a doc node in this mode.
  • off — update existing docs directly with update_node_content.

5. Cross-link

set_references from each doc node to the epics/features it documents, so the doc is reachable from the work it describes, not just from the doc list.

Rules

• Every doc node ends up bound to at least one component; create the component when the part of the system it documents has none.
• Every statement in the spec is backed by a file or a node; anything else belongs in Open questions & gaps, not asserted as fact. Never invent details.
• Don't paste source code into the spec — summarize structure, contracts and conventions.
• Re-running this skill on an already-bootstrapped project must update existing docs, not create duplicates: search (step 2) before every create.
• Write the spec and doc nodes in the same language as the user's prompt that triggered this run.