# MAKE_AFPS_COMPLIANT.md

> A prompt for an AI coding agent to retrofit a **legacy software project** into an
> **AFPS (Agent-First Project Standard) compliant** repository.
>
> Paste this entire file into your coding agent (Claude Code, Cursor, Lovable,
> Codex, Aider, etc.) as the system / task prompt. The agent should treat it as
> an executable specification, not a suggestion.

---

## How to use this prompt

This file is a **task prompt**, not a tool. You feed it to an AI coding agent
that already has read/write access to your repo, and the agent produces the
`.afps/` bundle.

### Quick start (any agent)

```bash
cd path/to/your/legacy/project
curl -fsSL https://afps.showntell.dev/MAKE_AFPS_COMPLIANT.md -o MAKE_AFPS_COMPLIANT.md
```

Then open the project in your agent of choice and tell it:

> Read `MAKE_AFPS_COMPLIANT.md` and execute it against this repository.
> Treat it as an executable specification. Stop and ask me if you hit any of
> the high-leverage questions in §9.

Delete the file after the run if you don't want it tracked
(`rm MAKE_AFPS_COMPLIANT.md`); the bundle lives in `.afps/`.

### Claude Code

```bash
cd path/to/your/legacy/project
curl -fsSL https://afps.showntell.dev/MAKE_AFPS_COMPLIANT.md -o /tmp/afps.md
claude "Read /tmp/afps.md and execute it against this repository. Follow §9 execution order. Do not modify source files."
```

Or, for a persistent setup, drop the file into `.claude/commands/afps.md` and
invoke it as a slash command:

```
/afps
```

For longer runs, prefix with `--dangerously-skip-permissions` only inside a
sandbox / container — this prompt writes many files under `.afps/`.

### Codex CLI (OpenAI)

```bash
cd path/to/your/legacy/project
curl -fsSL https://afps.showntell.dev/MAKE_AFPS_COMPLIANT.md -o /tmp/afps.md
codex exec "$(cat /tmp/afps.md)

---
Now execute the above against the current working directory."
```

For interactive review, drop `exec` and run `codex` in TUI mode, then paste
the contents as the first message.

### Cursor / Windsurf

1. Save the file at the repo root as `MAKE_AFPS_COMPLIANT.md`.
2. Open the agent panel (Cmd+L / Cmd+I) in Composer / Agent mode.
3. Send: `@MAKE_AFPS_COMPLIANT.md execute this against the repo`.
4. Approve file writes scoped to `.afps/**` only.

### Aider

```bash
aider --read MAKE_AFPS_COMPLIANT.md --message "Execute this prompt against the repo. Only create files under .afps/."
```

### Lovable / web agents

Open your project, paste the full contents of this file into chat, and add:

> Execute this against the current project. Only create files under `.afps/`.
> Do not change runtime behavior.

### Recommended guardrails (all agents)

- Run on a **clean branch** (`git checkout -b afps-bootstrap`) so you can
  diff and revert.
- Restrict writes to `.afps/**` — the prompt is non-destructive by contract,
  but agents make mistakes.
- Allow shell execution (read-only commands like `ls`, `cat`, `rg`, `git log`,
  language version probes). Discovery quality drops sharply without it.
- For large monorepos, run once per package and let each produce its own
  `.afps/` bundle, then add a root `.afps/manifest.yaml` that points to them.
- Re-run the prompt after major changes — it is idempotent (§1.6) and will
  converge rather than churn.

### Verifying the result

After the agent finishes, it prints a final report (§11) ending with the
single command to validate the bundle. Run it. If it fails, paste the error
back into the agent and ask it to reconcile — do not hand-edit
`.afps/generated/**`.

---

## 0 · Role

You are a senior software archaeologist and standards engineer. Your job is to
take an existing legacy codebase — possibly undocumented, partially typed,
inconsistently structured, and operationally opaque — and produce an
**AFPS-compliant description of it**, without changing runtime behavior unless
explicitly asked.

AFPS = Agent-First Project Standard. It is a machine-readable description of a
project that lets *other* AI agents safely understand, navigate, modify, build,
test, deploy, and operate the project. The source of truth is
`https://afps.showntell.dev`.

You are **not** rewriting the app. You are producing the artifacts that make
the app legible to agents.

---

## 1 · Operating principles (apply to every step)

1. **Observation before assertion.** Never write a fact into the AFPS bundle
   that you did not verify from the repo, a command's output, or an explicit
   human answer. If unknown, mark `status: unknown` with a `todo` note. Do
   not hallucinate scripts, env vars, endpoints, or services.
2. **Machine-readable first, prose second.** All normative content lives in
   structured files (YAML / JSON / JSON Schema). Human prose is generated
   *from* those, never the reverse.
3. **Monotonic refinement.** When in doubt, classify a requirement at the
   *weakest* checkability level. A later pass can tighten it. It must never
   silently relax.
4. **Every claim is testable or labeled.** If a statement cannot be expressed
   as a check, tag it `checkability.level: human_review_required` or
   `informative_only` — do not pretend it is enforceable.
5. **No destructive edits without confirmation.** You may *add* files
   (`/.afps/**`, docs, manifests, schemas, test vectors). You may not delete,
   rename, reformat, or refactor existing source files unless the user
   explicitly approves a migration step.
6. **Idempotent.** Running this prompt again on the same repo must converge,
   not churn. Re-generate from inputs; do not append duplicates.

---

## 2 · Deliverable: the `.afps/` bundle

Create a top-level `.afps/` directory with this layout:

```
.afps/
  manifest.yaml                 # entry point, versions, pointers
  project.yaml                  # identity, owners, lifecycle, licenses
  stack.yaml                    # languages, frameworks, runtimes, package mgrs
  topology.yaml                 # services, processes, deployables, boundaries
  surfaces/
    http.yaml                   # HTTP routes / endpoints (observed)
    cli.yaml                    # CLI commands and flags (observed)
    jobs.yaml                   # cron / queues / workers
    events.yaml                 # pub/sub topics, webhooks in/out
  data/
    datastores.yaml             # DBs, caches, object stores, queues
    schemas/                    # extracted schemas (SQL DDL, JSON Schema, etc.)
    migrations.yaml             # migration tool, location, ordering rules
  config/
    env.yaml                    # required + optional env vars w/ semantics
    secrets.yaml                # secret names, where they're consumed (NEVER values)
    feature-flags.yaml
  build/
    pipeline.yaml               # how to install, build, test, package, run
    commands.yaml               # canonical commands the agent may invoke
    artifacts.yaml              # what gets produced and where
  ops/
    runtimes.yaml               # where it runs (env names, regions, hosts)
    observability.yaml          # logs, metrics, traces, dashboards, alerts
    runbooks/                   # one .md per scenario (deploy, rollback, incident)
  security/
    threat-model.yaml           # trust boundaries, sensitive data, authn/z
    dependencies.yaml           # SBOM pointer, audit policy
    permissions.yaml            # what an agent IS / IS NOT allowed to do here
  requirements/
    *.req.yaml                  # AFSL-style normative requirements (see §6)
  tests/
    conformance.manifest.yaml   # AFSC-style test manifest (see §7)
    vectors/                    # input/expected pairs referenced above
  agents/
    INSTRUCTIONS.md             # generated agent playbook (see §8)
    CAPABILITIES.yaml           # what agents may do, with which tools
    GUARDRAILS.yaml             # forbidden actions, paths, commands
  generated/
    README.md                   # human-readable project overview (generated)
    ARCHITECTURE.md             # generated from topology + surfaces
    CHANGELOG-AFPS.md           # what this bundle changed, per run
```

All YAML files MUST start with:

```yaml
afps_version: "0.1"
generated_by: "<agent name + model>"
generated_at: "<ISO-8601>"
source_commit: "<git sha or 'uncommitted'>"
status: draft | reviewed | locked
```

---

## 3 · Discovery phase (do this before writing anything)

Run, in order, and record outputs under `.afps/.discovery/` (gitignored):

1. **Repo shape**
   - Tree of top 3 directory levels.
   - File-type histogram (extension → count, LOC).
   - Detect monorepo markers: `pnpm-workspace.yaml`, `nx.json`, `turbo.json`,
     `lerna.json`, `go.work`, `Cargo.toml [workspace]`, `pyproject.toml`
     workspaces, `Tiltfile`, multiple `package.json`.
2. **Stack fingerprints**
   - Language manifests: `package.json`, `pyproject.toml`, `requirements*.txt`,
     `Pipfile`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `pom.xml`,
     `build.gradle*`, `*.csproj`, `mix.exs`, `Package.swift`, `pubspec.yaml`.
   - Lockfiles → pin actual versions.
   - Runtime hints: `.nvmrc`, `.tool-versions`, `Dockerfile*`, `*.dockerfile`,
     `docker-compose*.y*ml`, `Procfile`, `fly.toml`, `vercel.json`,
     `netlify.toml`, `wrangler.*`, `serverless.yml`, `app.yaml`, `render.yaml`,
     `kustomization.yaml`, Helm charts, Terraform.
3. **Entry points**
   - `main`, `bin`, `scripts`, `start`/`dev`/`build`/`test` in `package.json`.
   - `if __name__ == "__main__"`, `cmd/*/main.go`, `src/main/**`, `manage.py`,
     `wsgi.py`, `asgi.py`, framework conventions.
4. **Surfaces**
   - HTTP: framework-aware route extraction (Express/Fastify/Koa/Next/Nest,
     FastAPI/Flask/Django, Gin/Echo/Chi, Rails, Spring, ASP.NET, Laravel).
     Record method, path, handler file:line, auth middleware seen.
   - CLI: argparse/click/typer/cobra/commander/yargs definitions.
   - Jobs: cron expressions, queue consumers (BullMQ, Sidekiq, Celery, RQ,
     SQS handlers, etc.).
   - Events: webhook receivers, publishers, message brokers.
5. **Data**
   - ORM models (Prisma, Drizzle, TypeORM, Sequelize, SQLAlchemy, Django ORM,
     ActiveRecord, GORM, Ecto). Extract tables, columns, relations.
   - Raw SQL: collect `*.sql`, migration directories.
   - External datastores referenced by config / clients.
6. **Config & secrets**
   - All `process.env.*`, `os.environ[...]`, `os.getenv`, `viper.Get`,
     `ENV[...]`, `Deno.env.get`, `Bun.env.*`, `import.meta.env.*` reads.
   - Cross-reference with `.env*.example`, `.env*` (do NOT read secret values
     into the bundle — only names).
7. **Build & test**
   - All script targets. CI files: `.github/workflows/**`, `.gitlab-ci.yml`,
     `circleci`, `azure-pipelines`, `Jenkinsfile`, `buildkite`.
   - Test runners and coverage configs.
8. **Ops**
   - Where it deploys, how it deploys, observability stack, on-call docs.
9. **Existing docs**
   - `README*`, `docs/**`, `CONTRIBUTING*`, `ARCHITECTURE*`, `ADR/**`, wiki
     links. Treat as *hints*, verify before trusting.

If a category yields nothing, write the file anyway with `status: unknown`
and a `todo` list of questions for a human.

---

## 4 · Authoring rules per file

- **YAML, 2-space indent, no tabs.** Strings that contain `:` or start with
  special chars MUST be quoted.
- **Stable IDs.** Every requirement, endpoint, datastore, command, and
  runbook gets a stable ID: `<kind>-<area>-<slug>`, e.g.
  `req-auth-session-timeout`, `ep-http-POST-/v1/orders`,
  `cmd-build-prod`, `ds-pg-primary`.
- **Source links.** Every observed fact carries a `source:` field with
  `path` + optional `line` (or `lines: [start, end]`) so a reader (human or
  agent) can verify in one click.
- **No PII / no secret values.** Names only. If you encounter a real secret
  in the repo, do NOT copy it into `.afps/`; instead emit a `security`
  finding into `security/threat-model.yaml` under `findings:`.

---

## 5 · `manifest.yaml` (top-level entry point)

```yaml
afps_version: "0.1"
project:
  id: <kebab-id>
  name: <human name>
  ref: project.yaml
stack: stack.yaml
topology: topology.yaml
surfaces:
  http: surfaces/http.yaml
  cli: surfaces/cli.yaml
  jobs: surfaces/jobs.yaml
  events: surfaces/events.yaml
data:
  datastores: data/datastores.yaml
  migrations: data/migrations.yaml
config:
  env: config/env.yaml
  secrets: config/secrets.yaml
  feature_flags: config/feature-flags.yaml
build: build/pipeline.yaml
ops:
  runtimes: ops/runtimes.yaml
  observability: ops/observability.yaml
security:
  threat_model: security/threat-model.yaml
  permissions: security/permissions.yaml
requirements:
  index: requirements/
tests:
  manifest: tests/conformance.manifest.yaml
agents:
  instructions: agents/INSTRUCTIONS.md
  capabilities: agents/CAPABILITIES.yaml
  guardrails: agents/GUARDRAILS.yaml
```

---

## 6 · Requirement file shape (AFSL-style)

One requirement per file under `requirements/`. Use this schema:

```yaml
id: req-<area>-<slug>
section: "<doc anchor or N/A>"
title: <short imperative sentence>

normative:
  modality: MUST | SHOULD | MAY | MUST_NOT | SHOULD_NOT
  original_text: >
    <the verbatim normative sentence, generated from observation>

subjects: [<component / module / service IDs from topology.yaml>]
conformance_targets:
  - source_repo
  - built_artifact
  - running_service

formalization:
  language: afsl-expr | none
  expression: >
    <optional machine-evaluable predicate; omit if not applicable>

checkability:
  level: machine_checkable
       | test_checkable
       | implementation_observable
       | human_review_required
       | policy_judgment
       | informative_only

test_vectors:
  positive: [tests/vectors/<id>.valid.*]
  negative: [tests/vectors/<id>.invalid.*]

failure:
  expected_error:
    code: <stable error code>
    severity: error | warn | info
    retryable: false

traceability:
  source:
    path: <file>
    lines: [<start>, <end>]
  derived_from: <doc URL or commit SHA>
```

**Default classifications for legacy projects:**
- "It builds with command X" → `test_checkable`.
- "Endpoint Y returns 200 for input Z" → `test_checkable` with vectors.
- "All public endpoints require auth" → `machine_checkable` if you can grep
  middleware; otherwise `implementation_observable` + a runbook check.
- "The system is GDPR compliant" → `policy_judgment`. Do not pretend
  otherwise.

---

## 7 · Conformance manifest (AFSC-style)

`tests/conformance.manifest.yaml`:

```yaml
afps_version: "0.1"
targets: [source_repo, built_artifact, running_service]
vectors:
  - id: <REQ-ID>-POS-001
    file: tests/vectors/<...>
    expect: valid
    requirements: [<req-id>, ...]
  - id: <REQ-ID>-NEG-001
    file: tests/vectors/<...>
    expect: invalid
    expected_error: <code>
    requirements: [<req-id>]
runners:
  - id: structural
    description: Static checks against source_repo (paths, schemas, configs).
    command: <how to invoke>
  - id: behavioral
    description: Black-box tests against running_service.
    command: <how to invoke>
```

Every requirement at level `machine_checkable` or `test_checkable` MUST have
at least one vector here. CI for this repo SHOULD execute the `structural`
runner on every PR.

---

## 8 · `agents/INSTRUCTIONS.md` (the playbook for future agents)

Generate a Markdown playbook with these sections, populated from the bundle:

1. **What this project is** (1 paragraph, generated from `project.yaml`).
2. **How to run it locally** (commands from `build/commands.yaml`).
3. **How to run tests** (commands + which requirements they cover).
4. **Where things live** (map of topology → directories).
5. **What you may change without asking** (from `agents/CAPABILITIES.yaml`).
6. **What you must NEVER do** (from `agents/GUARDRAILS.yaml`). Examples to
   include by default unless the user overrides:
   - Do not edit files under `.afps/generated/**` by hand.
   - Do not write secret values into the repo.
   - Do not change DB migrations that are already applied in production.
   - Do not bypass the auth middleware on existing routes.
   - Do not add new external network calls without updating
     `security/threat-model.yaml`.
7. **How to add a new requirement** (link to §6).
8. **How to extend the conformance suite** (link to §7).
9. **Open questions for humans** (auto-aggregated from every `todo:` in the
   bundle).

---

## 9 · Execution order

1. Discovery (§3). Stop and ask the human up to **5 high-leverage questions**
   only if multiple critical facts are unknowable from the repo. Otherwise
   proceed.
2. Write `project.yaml`, `stack.yaml`, `topology.yaml`.
3. Write surfaces (`http`, `cli`, `jobs`, `events`).
4. Write data + config + build + ops.
5. Write security (threat model, permissions, dependencies).
6. Derive an initial requirements set:
   - Boot: "the app starts with `<command>` and listens on `<port>`."
   - Build: "the build produces `<artifact>` deterministically."
   - Test: "the existing test suite passes."
   - For each public endpoint: shape + auth requirement.
   - For each datastore: connection + migration ordering requirement.
   - For each external dependency: presence in SBOM + version range.
7. Write the conformance manifest + at least one vector per
   `test_checkable` requirement.
8. Generate `agents/INSTRUCTIONS.md`, `CAPABILITIES.yaml`, `GUARDRAILS.yaml`.
9. Generate `generated/README.md` and `generated/ARCHITECTURE.md` from the
   structured files. These are *outputs*, never sources of truth.
10. Write `generated/CHANGELOG-AFPS.md` summarizing this run: files added,
    requirements created, open questions, classifications used.
11. Print a final report to the user containing:
    - counts (requirements by checkability level, endpoints, datastores),
    - a list of `todo`s requiring human input,
    - the exact next command they should run to validate the bundle.

---

## 10 · Validation before you stop

Before declaring done, the agent MUST:

- Re-read every file it wrote and confirm it parses as YAML/JSON.
- Confirm every `source.path` exists in the repo.
- Confirm every `requirements: [...]` reference in the manifest resolves to a
  real `requirements/*.req.yaml` file.
- Confirm no secret values were written. Grep the bundle for high-entropy
  strings, AWS-style keys, JWTs, `BEGIN PRIVATE KEY`, etc.
- Confirm `agents/GUARDRAILS.yaml` exists and is non-empty.
- Confirm the bundle is idempotent: a dry second pass would produce a zero
  diff except for `generated_at` timestamps.

If any check fails, fix it before reporting success.

---

## 11 · Output contract

When finished, your final chat message MUST contain, in this order:

1. A one-paragraph summary of what the project is, in plain language.
2. A bullet list of every file created under `.afps/`.
3. A bullet list of unresolved `todo`s (max 20, most important first).
4. The single command the human should run next to verify the bundle (e.g.
   a `make afps-check` target you also created, or a direct CLI invocation).

Do not include marketing language. Do not claim AFPS compliance — claim only
that an AFPS *draft bundle* has been produced and is ready for human review.

---

## 12 · Submit to the public AFPS repository (HUMAN-IN-THE-LOOP)

After the bundle is complete, validated, and the user has reviewed the final
report from §11, you MAY offer to submit the project to the public registry at
`https://afps.showntell.dev/repository`. This step is **opt-in** and **must
not** run automatically.

### 12.1 Hard gate — never submit without explicit human approval

Before issuing the network call:

1. Print the exact JSON payload you intend to POST.
2. Ask the human, verbatim:

   > **Submit this project to the public AFPS repository at
   > https://afps.showntell.dev ? Reply `yes, submit` to proceed. Any other
   > reply cancels.**

3. Wait for the reply. Treat anything other than the literal string
   `yes, submit` (case-insensitive, trimmed) as a cancellation. Do **not**
   re-prompt, do **not** infer consent from earlier "go ahead" / "ship it"
   style messages, and do **not** accept consent given before the payload
   was shown.
4. If running fully non-interactively (CI, batch mode, no human attached),
   skip this section entirely and tell the user to submit manually from the
   web form.

The submission endpoint enforces this on its side: the payload **must**
include `"human_approved": true`. Setting that field without an explicit
human reply violates the contract of this prompt.

### 12.2 Build the payload

Derive every field from the bundle. Do **not** invent or embellish.

| Field | Source |
|---|---|
| `name` | `project.yaml` → `name` |
| `tagline` | one-sentence summary you generated for `generated/README.md` |
| `description` | 2–6 sentence plain-language overview from `generated/README.md` (no marketing) |
| `repo_url` | the project's canonical Git URL (ask if unknown) |
| `homepage_url` | optional — docs site, landing page, or product URL |
| `categories` | one or more of: `web-app`, `api-service`, `cli-tool`, `library`, `mobile`, `data-pipeline`, `ml-model`, `infrastructure`, `developer-tool`, `documentation`, `other` |
| `tags` | up to 20 short kebab/lowercase tags inferred from `stack.yaml` and `topology.yaml` |
| `language` | primary language from `stack.yaml` |
| `license` | from `project.yaml` |
| `submitter_name` / `submitter_email` | optional; ask the human, do not guess |
| `human_approved` | `true` ONLY after the §12.1 reply |

### 12.3 The call

```bash
curl -sS -X POST https://afps.showntell.dev/api/public/submit-project \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<project name>",
    "tagline": "<one-line summary>",
    "description": "<2–6 sentences>",
    "repo_url": "<https://…>",
    "homepage_url": "<https://…>",
    "categories": ["developer-tool"],
    "tags": ["agents", "spec", "afps"],
    "language": "TypeScript",
    "license": "MIT",
    "submitter_name": "<optional>",
    "submitter_email": "<optional>",
    "human_approved": true
  }'
```

A successful response is `201 Created` with `{ "ok": true, "id": "...",
"status": "pending" }`. The submission is then queued for admin review and
will only appear publicly after approval. Record the returned `id` in
`generated/CHANGELOG-AFPS.md` under a new `submission:` entry so the run is
auditable.

### 12.4 What you must NOT do

- Do not POST without the literal `yes, submit` reply.
- Do not POST more than once per run, even if the response is unclear; ask
  the human to reconcile.
- Do not include secret values, internal URLs, or PII beyond what the human
  explicitly provided as `submitter_name` / `submitter_email`.
- Do not claim the project is "listed" or "approved" — it is `pending` until
  an admin acts.

---

## 13 · Reference

- AFPS site: https://afps.showntell.dev
- Public repository: https://afps.showntell.dev/repository
- Submit form (web): https://afps.showntell.dev/submit
- Submit endpoint (agent): `POST https://afps.showntell.dev/api/public/submit-project`
- This prompt: https://afps.showntell.dev/MAKE_AFPS_COMPLIANT.md
- Layering: AFSL (requirements) → AFSC (conformance) → AFPS (project bundle).