Feature 01 task 6: AGENTS.md, CLAUDE.md, README and architecture docs #7

Merged

approver_agent merged 4 commits from task/agents-docs_de5d4031-1df9-42e0-910a-5a8929bec0d4 into feature/19ad7feb-aba0-4b76-ab70-c47d71ed5e76-repository-scaffold-and-ci 2026-10-03 00:26:16 -04:00

Conversation 3 Commits 4 Files Changed 4

+435

dev_agent commented 2026-10-03 00:17:22 -04:00

Member

Copy Link

Copy Source

Implements task de5d4031 (Feature 01, task 6 of 6).

Adds AGENTS.md (authoritative agent guide: house rules, approved dependencies, quality floor, repo layout, branch/PR/merge conventions, CTXD + Maestro locations, GLOSSARY vocabulary, never use tea), CLAUDE.md (exactly '@AGENTS.md'), README.md (purpose + make dev quick start), and docs/ARCHITECTURE.md (mirrors the CTXD CONTEXT.MD architecture section, corrected against the CTXD data model and lifecycle in a second commit).

Evidence: gofmt -l . empty; go vet, go test -race -count=1, go build ./... pass; all 15 local links in the docs resolve; CLAUDE.md is exactly '@AGENTS.md'. Local links point at design/ requirements and UI handoff, tokens.css, Makefile, Dockerfile, CI workflow, and docs/ARCHITECTURE.md.

Base: feature/19ad7feb-aba0-4b76-ab70-c47d71ed5e76-repository-scaffold-and-ci (ec13423).

Implements task de5d4031 (Feature 01, task 6 of 6). Adds AGENTS.md (authoritative agent guide: house rules, approved dependencies, quality floor, repo layout, branch/PR/merge conventions, CTXD + Maestro locations, GLOSSARY vocabulary, never use tea), CLAUDE.md (exactly '@AGENTS.md'), README.md (purpose + make dev quick start), and docs/ARCHITECTURE.md (mirrors the CTXD CONTEXT.MD architecture section, corrected against the CTXD data model and lifecycle in a second commit). Evidence: gofmt -l . empty; go vet, go test -race -count=1, go build ./... pass; all 15 local links in the docs resolve; CLAUDE.md is exactly '@AGENTS.md'. Local links point at design/ requirements and UI handoff, tokens.css, Makefile, Dockerfile, CI workflow, and docs/ARCHITECTURE.md. Base: feature/19ad7feb-aba0-4b76-ab70-c47d71ed5e76-repository-scaffold-and-ci (ec13423).

dev_agent added 2 commits 2026-10-03 00:17:22 -04:00

Add AGENTS.md, CLAUDE.md, README and architecture docs ... 998898c549

AGENTS.md is the authoritative agent guide: house rules, approved
dependencies, quality floor, repository layout, branch and merge
conventions, where context and work tracking live, GLOSSARY vocabulary
and the rule never to use tea. CLAUDE.md imports it. README gives the
purpose and a make dev quick start. docs/ARCHITECTURE.md mirrors the
CTXD CONTEXT.MD architecture section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Correct architecture doc to match the CTXD architecture section ... 37f6200250

Replace the data model table with the CTXD tables and columns (recipes
are fetched recipe pages; dinners hold the meal record and lifecycle),
fix the dinner lifecycle (Pass leads to archived; tried can return to
quest_log), add the session cookie attributes and expiry, require the
session cookie and CSRF header on /api/v1, make the ai_runs purge daily,
use the handoff routes plus the CTXD settings routes, and remove details
not supported by CTXD, the requirements or the UI handoff.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

review_agent reviewed 2026-10-03 00:20:05 -04:00

review_agent left a comment

Member

Copy Link

Copy Source

Independent review — Codex gpt-6-sol, reasoning high

Verdict: CHANGES_REQUIRED
Reviewed SHA: 37f6200250910877f1c9521953eba3497c395b0e

{
  "verdict": "CHANGES_REQUIRED",
  "reviewed_sha": "37f6200250910877f1c9521953eba3497c395b0e",
  "summary": "The guide, CLAUDE.md, and local links meet their requirements, and all requested Go checks pass. The architecture and quick-start docs need corrections.",
  "findings": [
    {
      "id": "F1",
      "severity": "medium",
      "location": "docs/ARCHITECTURE.md:23",
      "failure_case": "A deployment could route traffic to port 8090 inside the container instead of the service listener.",
      "evidence": "The diagram calls 8090 the Go service port. The supplied architecture specifies 8090 as the host port, while Dockerfile exposes 8080.",
      "suggested_correction": "Show the mapping explicitly as host 8090 to container 8080."
    },
    {
      "id": "F2",
      "severity": "medium",
      "location": "docs/ARCHITECTURE.md:24",
      "failure_case": "A deployment could expose the recipe-search sidecar outside the compose network.",
      "evidence": "The topology lists the searxng sidecar but omits the supplied requirement that it be internal-network-only.",
      "suggested_correction": "State that searxng is reachable only on the internal compose network."
    },
    {
      "id": "F3",
      "severity": "low",
      "location": "docs/ARCHITECTURE.md:56",
      "failure_case": "The architecture leaves the required log format unspecified.",
      "evidence": "It says log/slog is structured; the supplied backend architecture specifies log/slog JSON.",
      "suggested_correction": "Specify JSON logging."
    },
    {
      "id": "F4",
      "severity": "medium",
      "location": "docs/ARCHITECTURE.md:156",
      "failure_case": "Implementers could add rollover and purge controls to household_settings based on this description.",
      "evidence": "The text says all scheduler defaults in the table are set in household_settings, but the supplied household_settings fields have no week_rollover or ai_runs purge setting.",
      "suggested_correction": "Distinguish household-configurable times from the fixed rollover and purge schedules."
    },
    {
      "id": "F5",
      "severity": "low",
      "location": "README.md:16",
      "failure_case": "A reader using an early Node.js 22 release may find the quick start unsupported.",
      "evidence": "README says Node.js 22, but the checked-in package lock requires Node >=22.12.0 for Vite and Vitest.",
      "suggested_correction": "Specify Node.js 22.12 or newer."
    }
  ]
}

---

Posted unaltered by review_agent. This is transport, not a second review.

## Independent review — Codex `gpt-6-sol`, reasoning high Verdict: **CHANGES_REQUIRED** Reviewed SHA: `37f6200250910877f1c9521953eba3497c395b0e` ```json { "verdict": "CHANGES_REQUIRED", "reviewed_sha": "37f6200250910877f1c9521953eba3497c395b0e", "summary": "The guide, CLAUDE.md, and local links meet their requirements, and all requested Go checks pass. The architecture and quick-start docs need corrections.", "findings": [ { "id": "F1", "severity": "medium", "location": "docs/ARCHITECTURE.md:23", "failure_case": "A deployment could route traffic to port 8090 inside the container instead of the service listener.", "evidence": "The diagram calls 8090 the Go service port. The supplied architecture specifies 8090 as the host port, while Dockerfile exposes 8080.", "suggested_correction": "Show the mapping explicitly as host 8090 to container 8080." }, { "id": "F2", "severity": "medium", "location": "docs/ARCHITECTURE.md:24", "failure_case": "A deployment could expose the recipe-search sidecar outside the compose network.", "evidence": "The topology lists the searxng sidecar but omits the supplied requirement that it be internal-network-only.", "suggested_correction": "State that searxng is reachable only on the internal compose network." }, { "id": "F3", "severity": "low", "location": "docs/ARCHITECTURE.md:56", "failure_case": "The architecture leaves the required log format unspecified.", "evidence": "It says log/slog is structured; the supplied backend architecture specifies log/slog JSON.", "suggested_correction": "Specify JSON logging." }, { "id": "F4", "severity": "medium", "location": "docs/ARCHITECTURE.md:156", "failure_case": "Implementers could add rollover and purge controls to household_settings based on this description.", "evidence": "The text says all scheduler defaults in the table are set in household_settings, but the supplied household_settings fields have no week_rollover or ai_runs purge setting.", "suggested_correction": "Distinguish household-configurable times from the fixed rollover and purge schedules." }, { "id": "F5", "severity": "low", "location": "README.md:16", "failure_case": "A reader using an early Node.js 22 release may find the quick start unsupported.", "evidence": "README says Node.js 22, but the checked-in package lock requires Node >=22.12.0 for Vite and Vitest.", "suggested_correction": "Specify Node.js 22.12 or newer." } ] } ``` --- Posted unaltered by `review_agent`. This is transport, not a second review.

dev_agent added 1 commit 2026-10-03 00:20:44 -04:00

Fix architecture and README accuracy findings from review ... bed51ed2bd

- Topology: show the port mapping host 8090 -> container 8080, and note
  that searxng is internal to the compose network with no published port.
- Backend: logging is log/slog JSON.
- Scheduler: only the household-configurable times live in
  household_settings; week_rollover and the ai_runs purge are fixed.
- README: state the Node.js floor required by the committed lockfile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

review_agent reviewed 2026-10-03 00:23:37 -04:00

review_agent left a comment

Member

Copy Link

Copy Source

Independent review — Codex gpt-6-sol, reasoning high

Verdict: CHANGES_REQUIRED
Reviewed SHA: bed51ed2bdb0c2cad3ea94a73ca9ed7dea85e5c1

{
  "verdict": "CHANGES_REQUIRED",
  "reviewed_sha": "bed51ed2bdb0c2cad3ea94a73ca9ed7dea85e5c1",
  "summary": "The required guide and architecture content is present, all local links resolve, and the Go formatting, vet, race tests, and build pass. The README quick start needs two corrections.",
  "findings": [
    {
      "id": "F1",
      "severity": "medium",
      "location": "README.md:22",
      "failure_case": "On a shared development host, another user in the developer’s group can read the generated secret key.",
      "evidence": "The commands create the directory and secret file without setting permissions. This host’s umask is 0002, which yields a group-accessible directory (775) and group-readable key file (664).",
      "suggested_correction": "Set umask 077 before creating the directory and key, or explicitly set the directory to 700 and the key to 600."
    },
    {
      "id": "F2",
      "severity": "low",
      "location": "README.md:16",
      "failure_case": "A reader may use a Node.js version advertised as supported, such as 23.x or 24.0, for which the locked jsdom package declares no support.",
      "evidence": "The README says “22.22.2 or newer,” while web/package-lock.json specifies jsdom’s Node engine as ^22.22.2 || ^24.15.0 || >=26.0.0.",
      "suggested_correction": "State the supported Node.js version ranges exactly."
    }
  ]
}

---

Posted unaltered by review_agent. This is transport, not a second review.

## Independent review — Codex `gpt-6-sol`, reasoning high Verdict: **CHANGES_REQUIRED** Reviewed SHA: `bed51ed2bdb0c2cad3ea94a73ca9ed7dea85e5c1` ```json { "verdict": "CHANGES_REQUIRED", "reviewed_sha": "bed51ed2bdb0c2cad3ea94a73ca9ed7dea85e5c1", "summary": "The required guide and architecture content is present, all local links resolve, and the Go formatting, vet, race tests, and build pass. The README quick start needs two corrections.", "findings": [ { "id": "F1", "severity": "medium", "location": "README.md:22", "failure_case": "On a shared development host, another user in the developer’s group can read the generated secret key.", "evidence": "The commands create the directory and secret file without setting permissions. This host’s umask is 0002, which yields a group-accessible directory (775) and group-readable key file (664).", "suggested_correction": "Set umask 077 before creating the directory and key, or explicitly set the directory to 700 and the key to 600." }, { "id": "F2", "severity": "low", "location": "README.md:16", "failure_case": "A reader may use a Node.js version advertised as supported, such as 23.x or 24.0, for which the locked jsdom package declares no support.", "evidence": "The README says “22.22.2 or newer,” while web/package-lock.json specifies jsdom’s Node engine as ^22.22.2 || ^24.15.0 || >=26.0.0.", "suggested_correction": "State the supported Node.js version ranges exactly." } ] } ``` --- Posted unaltered by `review_agent`. This is transport, not a second review.

dev_agent added 1 commit 2026-10-03 00:24:19 -04:00

Restrict dev secret permissions and state exact Node.js ranges in README ... 60f977d50c

The quick start now sets the dev data directory to 700 and the secret key
file to 600, so other local users cannot read the key. The prerequisites
state the exact supported Node.js ranges from the lockfile's jsdom engine
(^22.22.2 || ^24.15.0 || >=26.0.0) instead of "22.22.2 or newer".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

review_agent reviewed 2026-10-03 00:26:01 -04:00

review_agent left a comment

Member

Copy Link

Copy Source

Independent review — Codex gpt-6-sol, reasoning high

Verdict: APPROVED
Reviewed SHA: 60f977d50c5b15303804b7acf9e7e0ceae05800e

{
  "verdict": "APPROVED",
  "reviewed_sha": "60f977d50c5b15303804b7acf9e7e0ceae05800e",
  "summary": "All required documentation is present and consistent with the supplied CTXD facts. Local links resolve; gofmt, go vet, race tests, and go build pass.",
  "findings": []
}

---

Posted unaltered by review_agent. This is transport, not a second review.

## Independent review — Codex `gpt-6-sol`, reasoning high Verdict: **APPROVED** Reviewed SHA: `60f977d50c5b15303804b7acf9e7e0ceae05800e` ```json { "verdict": "APPROVED", "reviewed_sha": "60f977d50c5b15303804b7acf9e7e0ceae05800e", "summary": "All required documentation is present and consistent with the supplied CTXD facts. Local links resolve; gofmt, go vet, race tests, and go build pass.", "findings": [] } ``` --- Posted unaltered by `review_agent`. This is transport, not a second review.

approver_agent merged commit 9f4537d0cb into feature/19ad7feb-aba0-4b76-ab70-c47d71ed5e76-repository-scaffold-and-ci 2026-10-03 00:26:16 -04:00

dev_agent referenced this pull request 2026-10-03 00:27:01 -04:00

Feature 01: Repository Scaffold and CI #8

Sign in to join this conversation.

Reviewers

No Reviewers

review_agent

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

approver_agent (The Approver) chatgpt claude-ai Claude-Code codex (Codex) dev_agent grok opencode orchestrator-agent overseer (Joshua) review_agent (The Reviewer)

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Maniacs_Mansion/MealQuest#7