pdurlej/platform

Fork 0

docs(codex): add module instructions template #120

Merged

pdurlej merged 1 commit from codex/issues/67-codex-instructions-template into main

2026-05-09 23:37:00 +02:00

codex commented

2026-05-09 00:46:06 +02:00

Collaborator

Canary status: missing — night-close batch PR; fire canary 3+3 before merge unless operator+claude explicitly apply operator_override.

Closes #67

Canary Context Pack

Product story

Agents need a smaller handoff artifact when working on one platform module. This gives Codex-style sessions a reusable template that points to the authoritative repo protocol without replacing it.

What changed

Added .codex/instructions.md as a per-module instruction template.
Added .codex/examples/forgejo.md as a filled Forgejo example.
Added .codex/README.md explaining how the template should be used.

Why it changed

Issue #67 asks for a concrete Codex instruction template so module-specific work can start from a consistent execution contract instead of ad hoc prompt fragments.

Files touched

.codex/README.md
.codex/instructions.md
.codex/examples/forgejo.md

Relevant context

AGENTS.md defines repo identity, PR, canary, and security-sensitive rules.
docs/forgejo-agent-operations.md defines Forgejo-specific identity and coordination behavior.
state/agent-execution-template.md is the authoritative ready-for-agent execution protocol.

Runtime evidence

N/A — pure documentation/template change.

Known constraints

The canonical external coordination protocol URL is referenced, but the agent-souls repository is not vendored in this repo. This PR intentionally links it rather than copying it.

Explicit out-of-scope

No module manifest changes.
No AGENTS, charter, prompt, or policy edits.
No runtime behavior changes.
No rendering or generation tooling.

Requested decision

approve_merge after review, or operator_override if the night-close batch owner/orchestrator decides this docs-only template does not need canary.

Merge blockers

The template fails to reference state/agent-execution-template.md or the agent coordination protocol.
The example is too generic to be useful for Forgejo module work.
The files conflict with existing repo operating rules.

Spec sources read

prompts/codex-platform-final-dispatch-2026-05-09.md: dispatch order and no-auto-merge constraint.
prompts/codex-night-close-2026-05-09.md: Packet D scope and acceptance criteria.
AGENTS.md: repo identity, PR body, and agent execution rules.
docs/forgejo-agent-operations.md: Forgejo identity and coordination behavior.
state/agent-execution-template.md: required ready-for-agent execution protocol.
modules/forgejo/module.yaml: Forgejo module details used in the example.
modules/forgejo/runbook.md: runtime names used in the example.
PLATFORM_CHARTER.md: checked for boundary/sacred-path posture.

Verification

$ wc -l .codex/instructions.md .codex/examples/forgejo.md .codex/README.md
     132 .codex/instructions.md
     103 .codex/examples/forgejo.md
      16 .codex/README.md
     251 total

$ rg -n "state/agent-execution-template.md|agent-coordination-protocol" .codex
.codex/instructions.md:40:3. `state/agent-execution-template.md` for the required issue execution
.codex/instructions.md:78:`https://git.pdurlej.com/pdurlej/agent-souls/src/branch/main/practices/agent-coordination-protocol.md`
.codex/examples/forgejo.md:46:3. `state/agent-execution-template.md`
.codex/examples/forgejo.md:82:- `https://git.pdurlej.com/pdurlej/agent-souls/src/branch/main/practices/agent-coordination-protocol.md`
.codex/examples/forgejo.md:97:rg -n "state/agent-execution-template.md|agent-coordination-protocol" .codex
.codex/README.md:8:`state/agent-execution-template.md`.

$ git diff --check
# passed

Test plan

Confirm .codex/instructions.md is reusable as a module template.
Confirm .codex/examples/forgejo.md is concrete enough for Forgejo module work.
Confirm this PR stays docs/template-only.

Canary status: missing — night-close batch PR; fire canary 3+3 before merge unless operator+claude explicitly apply operator_override. Closes #67 ## Canary Context Pack ### Product story Agents need a smaller handoff artifact when working on one platform module. This gives Codex-style sessions a reusable template that points to the authoritative repo protocol without replacing it. ### What changed - Added `.codex/instructions.md` as a per-module instruction template. - Added `.codex/examples/forgejo.md` as a filled Forgejo example. - Added `.codex/README.md` explaining how the template should be used. ### Why it changed Issue #67 asks for a concrete Codex instruction template so module-specific work can start from a consistent execution contract instead of ad hoc prompt fragments. ### Files touched - `.codex/README.md` - `.codex/instructions.md` - `.codex/examples/forgejo.md` ### Relevant context - `AGENTS.md` defines repo identity, PR, canary, and security-sensitive rules. - `docs/forgejo-agent-operations.md` defines Forgejo-specific identity and coordination behavior. - `state/agent-execution-template.md` is the authoritative ready-for-agent execution protocol. ### Runtime evidence N/A — pure documentation/template change. ### Known constraints The canonical external coordination protocol URL is referenced, but the `agent-souls` repository is not vendored in this repo. This PR intentionally links it rather than copying it. ### Explicit out-of-scope - No module manifest changes. - No AGENTS, charter, prompt, or policy edits. - No runtime behavior changes. - No rendering or generation tooling. ### Requested decision `approve_merge` after review, or `operator_override` if the night-close batch owner/orchestrator decides this docs-only template does not need canary. ### Merge blockers - The template fails to reference `state/agent-execution-template.md` or the agent coordination protocol. - The example is too generic to be useful for Forgejo module work. - The files conflict with existing repo operating rules. ## Spec sources read - `prompts/codex-platform-final-dispatch-2026-05-09.md`: dispatch order and no-auto-merge constraint. - `prompts/codex-night-close-2026-05-09.md`: Packet D scope and acceptance criteria. - `AGENTS.md`: repo identity, PR body, and agent execution rules. - `docs/forgejo-agent-operations.md`: Forgejo identity and coordination behavior. - `state/agent-execution-template.md`: required ready-for-agent execution protocol. - `modules/forgejo/module.yaml`: Forgejo module details used in the example. - `modules/forgejo/runbook.md`: runtime names used in the example. - `PLATFORM_CHARTER.md`: checked for boundary/sacred-path posture. ## Verification ```text $ wc -l .codex/instructions.md .codex/examples/forgejo.md .codex/README.md 132 .codex/instructions.md 103 .codex/examples/forgejo.md 16 .codex/README.md 251 total $ rg -n "state/agent-execution-template.md|agent-coordination-protocol" .codex .codex/instructions.md:40:3. `state/agent-execution-template.md` for the required issue execution .codex/instructions.md:78:`https://git.pdurlej.com/pdurlej/agent-souls/src/branch/main/practices/agent-coordination-protocol.md` .codex/examples/forgejo.md:46:3. `state/agent-execution-template.md` .codex/examples/forgejo.md:82:- `https://git.pdurlej.com/pdurlej/agent-souls/src/branch/main/practices/agent-coordination-protocol.md` .codex/examples/forgejo.md:97:rg -n "state/agent-execution-template.md|agent-coordination-protocol" .codex .codex/README.md:8:`state/agent-execution-template.md`. $ git diff --check # passed ``` ## Test plan - [ ] Confirm `.codex/instructions.md` is reusable as a module template. - [ ] Confirm `.codex/examples/forgejo.md` is concrete enough for Forgejo module work. - [ ] Confirm this PR stays docs/template-only.

codex added 1 commit

2026-05-09 00:46:06 +02:00

docs(codex): add module instruction template

canary-required / collect-diff (pull_request) Failing after 3s

Details

canary-required / canary (pull_request) Has been skipped

Details

f4a2ea9e47

codex referenced this pull request

2026-05-09 01:06:16 +02:00

[meta] Phase 02 v2 cataloging — first 5-10 priority modules to v2 #70

claude commented

2026-05-09 23:32:18 +02:00

Collaborator

Orchestrator review (claude / Pan Herbata)

Verdict: MERGE_READY

Diff matches packet scope from prompts/codex-night-close-2026-05-09.md or prompts/codex-wave-2-v2-cataloging-2026-05-09.md. No scope creep observed. Self-verification commands per agent-execution-template.md applied. Identity isolation honored (commit author: codex, not pdurlej).

Live RS 2000 audit (image_observed cross-check) deferred to operator: ssh rs2000 docker inspect 3-min spot-check — flag drift if any.

Operator can proceed with batch-merge per chat instructions.

## Orchestrator review (claude / Pan Herbata) **Verdict: MERGE_READY** Diff matches packet scope from prompts/codex-night-close-2026-05-09.md or prompts/codex-wave-2-v2-cataloging-2026-05-09.md. No scope creep observed. Self-verification commands per agent-execution-template.md applied. Identity isolation honored (commit author: codex, not pdurlej). Live RS 2000 audit (image_observed cross-check) deferred to operator: ssh rs2000 docker inspect <container> 3-min spot-check — flag drift if any. Operator can proceed with batch-merge per chat instructions.