operating-model-bootstrap

Files (19)

• SKILL.md
• openai.yaml · agents/
• CHANGELOG.template.md · assets/
• CHECKPOINT.template.yaml · assets/
• DELIVERY-WORKFLOW.template.md · assets/
• EVIDENCE-MANIFEST.template.yaml · assets/
• OPERATING-MANUAL.md · assets/
• PROJECT-OPERATING-PROFILE.template.md · assets/
• ROADMAP.template.md · assets/
• STATUS.template.md · assets/
• VISION.template.md · assets/
• AGENTS.md.template · assets/adapters/
• CLAUDE.md.template · assets/adapters/
• GEMINI.md.template · assets/adapters/
• DAY-ONE-EXAMPLE.md · references/
• release-contract.md · references/
• bootstrap_operating_model.py · scripts/
• inspect_repo.py · scripts/
• validate_operating_model.py · scripts/

SKILL.md (first lines)

# Operating Model Bootstrap

## When to use

- Starting a new repository or team project that will use AI agents or agent-harness skills
- Adopting this harness into an existing project for the first time
- Defining or repairing authority, risk tiers, lane isolation, or evidence-binding contracts
- Coordinating parallel human and agent lanes safely (worktrees, ownership, integration)
- Binding review to an exact candidate commit before R2/R3 work
- Correcting fragmented or contradictory rules across AGENTS.md, CLAUDE.md, and GEMINI.md

---

Establish a portable operating kernel and one tracked project profile. Treat humans,
agents, skills, tools, and gates as one delivery system with explicit authority,
ownership, evidence, and completion semantics. The day-one seed lets a new team begin
system design and delivery planning while explicitly owned project unknowns are resolved.

## Resolve the installation before running scripts

Keep the working directory at the consumer project root. Find this `SKILL.md` in the
host’s selected project, user or plugin installation, and resolve `scripts/` beside it.
Use that absolute script path; do not assume `.agents/skills/` exists in the consumer.
In the commands below, replace `<bootstrap-skill-dir>` with that discovered directory.
Never run bootstrap against the installed package or a global home directory. If more
than one installation is available, use the project’s declared version/source and resolve
ambiguity before mutation. Preserve existing adapters; conflicts require a deliberate merge.

## Project awareness — seven areas to establish at init

The bootstrap must establish or explicitly own each of the following. Required areas must
be answered before the profile leaves `seed` state. Optional areas have a recommended
default; record `not yet established — owner: role; required before: trigger` for any
unknown rather than leaving it blank or fabricating a value.

| # | Area | Status | Default if not declared |
|---|---|---|---|
| 1 | Product vision, objectives, actors, scope, out-of-scope, SOW / acceptance record | **Required** | None — must be declared |
| 2 | Team roster: PO, SMEs, integration owner, reviewer roles, escalation path | **Required** | None — must be declared |
| 3 | Technical stack: language, framework, architecture, repos, interfaces, runtime | **Required** | None — must be declared |
| 4 | Tooling: package manager, linter, type checker, unit / integration / e2e test commands | Optional — recommended defaults | Linting + validation + unit tests minimum |
| 5 | Cloud, hosting, data classification, residency, compliance, approved-vendor constraints | Optional — advised | Deduced from stack; invoke `governance-guardrail` to confirm policy alignment |
| 6 | Automation: CI/CD, branch policy, release process, deployment owner, rollback | Optional — default provided | GitHub SemVer + tag-based releases; invoke `release-manager` to document and confirm |
| 7 | Delivery controls: source of truth, issue/PR conventions, DoD, escalation triggers | Optional — default provided | GitHub stack; this repository's issues, ADRs, and architecture docs are the source of truth |

### Backfill from an existing repo

When adopting into a repo that already has code, do not present a blank seven-area form.
Run the read-only inspection pass to pre-fill what the repository already reveals:

```bash
python3 "<bootstrap-skill-dir>/scripts/inspect_repo.py" .
```

It reads manifests, tool configs, CI, `CODEOWNERS`, and docs, and prints **inferred**
findings — each a machine guess with an evidence pointer and the exact
`inferred — source: <evidence>; confirm: <role>` marker to paste into the profile. Rules:

- Transcribe each finding into the profile as its `inferred` marker; **never** silently
  promote it to a verified fact.
- Confirm inferred fields **one at a time** with the named human; a confirmed field
  becomes a plain verified value. The profile cannot go `active` while any `inferred`
  field remains (the validator enforces this).
- The pass is read-only and **never infers authority** — `CODEOWNERS` handles are roster
  *candidates* only; role and accountability stay `unknown` until a human assigns them.

### Init artefacts

The initializer script seeds structure, not decisions. Running `bootstrap` (or the `init`
command, which runs `bootstrap` first) creates these records with template content to be
grounded from verified project evidence:

- `docs/operating-model/PROJECT-OPERATING-PROFILE.md` — the project contract, holding the
  seven-area answers above.
- `docs/VISION.md` — product vision, objectives, actors, scope, and out-of-scope (area 1).
- `docs/ROADMAP.md` — the big-picture scope of work: ordered outcome gates, seeded
  unpopulated. The team adds dates as the Product Owner confirms them.
- `docs/STATUS.md` — the derived situation-report structure, seeded unpopulated.
- `docs/operating-model/DELIVERY-WORKFLOW.md`, `CHANGELOG.md`, and the
  `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` adapters.

The script seeds structure; the agent records the decisions. As part of the bootstrap
workflow, capture the choices made during init as durable, referenceable authority:

- **Baseline ADR** — author the project's first architecture decision record at its ADR
  convention (`ADR/ADR-0000-baseline-structure-DRAFT.md`, approved to
  `-approved.md`; see `the-architect`),
  capturing every choice confirmed or deferred during init, with the owner and resolving
  trigger for each explicit unknown. This is the authority record for the starting
  structure.
- **First status entry** — add one entry to `docs/STATUS.md` recording the initialization
  event and the open unknowns. This records what happened, not invented progress; roadmap
  outcomes stay unpopulated until the Product Owner validates them.

Do not fabricate answers to populate any of these files. An honest `unknown — owner: X;
required before: Y` is better than a plausible-sounding invention that will mislead every
agent that later reads the profile.

## Portability boundary

The operating model is model-, vendor-, and IDE-agnostic. Thin surface adapters only make
the same contract discoverable and invocable. They may not change authority, risk,
evidence, review, or completion semantics. This is a team-project harness bootstrap, not a
production application scaffold or a substitute for project/domain controls.

## Load the assets

Read the four contract assets before editing the target project:

- `assets/OPERATING-MANUAL.md` — released vendor-neutral normative kernel; copy it unchanged.
- `assets/PROJECT-OPERATING-PROFILE.template.md` — project-specific contract.
- `assets/CHECKPOINT.template.yaml` — durable state for R2/R3 work.
- `assets/EVIDENCE-MANIFEST.template.yaml` — exact-candidate evidence and review record.

Read the five planning-seed assets before initialising project delivery records:

- `assets/VISION.template.md` — durable product direction and initial focus.
- `assets/DELIVERY-WORKFLOW.template.md` — project mapping of the shared lifecycle.
- `assets/ROADMAP.template.md` — ordered outcome gates, initially unpopulated.

From jpantsjoha/ai-native-developer-experience, Apache-2.0.

More from jpantsjoha/ai-native-developer-experience