Skip to content

docs: render org procedures inline for agents-target consumers - #2

Merged
shivros merged 2 commits into
mainfrom
runner/COD-444-skills-reachable-config
Sep 2, 2026
Merged

docs: render org procedures inline for agents-target consumers#2
shivros merged 2 commits into
mainfrom
runner/COD-444-skills-reachable-config

Conversation

@shivros

@shivros shivros commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Summary

Makes every central TechGodHQ procedure reachable to generic AGENTS.md consumers without duplicating source text.

Problem (COD-444): Creed's agents target renders only config: entries into AGENTS.mdskills: entries render to SkillDir outputs, which the agents target lacks. The org constitution pointed at .creed/skills/{architecture,implementation,review}.md, paths that don't exist in Hydra/Iris consumers.

Fix:

  • .creed/manifest.yaml: declare the three procedure files as config: entries (rendered inline into AGENTS.md), replacing the skills: declarations. One authoritative source file per procedure is preserved — the files under .creed/skills/ are untouched.
  • .creed/config/org.md: pointer paragraph now references the rendered sections ("follow the Architecture Skill below") instead of nonexistent consumer paths.
  • AGENTS.md: regenerated — constitution + all three procedures render inline, org layer preceding consumer context deterministically.
  • README.md: updated to describe inline rendering and the shipped layered-source consumption model (was describing the removed pointer design and pre-layered status).

Probe: real Hydra layered render

Creed binary built from main afe5dbb (layered sources; the installed v0.3.0 rejects layered manifests). Probe worktree at Hydra origin/main (c524ccc) with the org layer pinned to this branch's head 9ac26ff0c3a374e4ce1ca3aa999c36c8e517f06f:

$ /tmp/creed validate
Validation passed
$ /tmp/creed sync
agents: 1 written, 0 skipped, 0 failed
$ /tmp/creed sync        # idempotency
agents: 0 written, 1 skipped, 0 failed
$ /tmp/creed diff
$ echo $?
0
$ grep -c "\.creed/skills" AGENTS.md
0                       # zero dangling pointers

Rendered consumer AGENTS.md structure (org procedures precede Hydra's local context deterministically):

1:# TechGodHQ Org Context
49:# Architecture Skill
94:# Implementation Skill
150:# Org Review Skill
205:# Hydra Project Context
238:# Development Instructions
272:# Git / PR Rules

Also verified in agent-context itself: validate / sync / second sync (0 written, 1 skipped) / diff exit 0, and the committed AGENTS.md matches the render.

Notes

  • Dormant until consumers re-pin: Hydra/Iris pin the org layer to a commit SHA; they see no change (and no breakage) until they move to 9ac26ff+ — that's COD-446/COD-447, both currently blocked on the Creed v0.4.x release (COD-445).
  • Silent-override hazard (documented tradeoff): a consumer declaring a config named org/architecture/implementation/review would last-wins-replace the org entry. No current consumer does. Sanctioned by the issue's acceptance criteria.
  • Creed's duplicate_source_path validation forbids declaring the same file as both skill and config, so the skills: entries were removed rather than kept alongside.

Closes COD-444

@shivros

shivros commented Aug 27, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Automated Review Panel

Reviewer A (glm-5.1)

Verdict: APPROVE

Verification performed (all independent, real execution):

  • Located the actual repo at /home/shiv/agent-context (branch runner/COD-444-skills-reachable-config); re-ran gates: creed validate ✓, sync ✓, second sync idempotent (0 written, 1 skipped) ✓, diff exit 0 ✓.
  • Built creed from /home/shiv/creed @ afe5dbb and ran a fresh layered consumer probe pinned to the branch head: validate ✓, sync 1 written ✓, second sync idempotent ✓, diff exit 0 ✓, zero .creed/skills references in the rendered consumer AGENTS.md, org + all three skill sections render before the consumer's own section deterministically.
  • Confirmed the three skill bodies render verbatim into the consumer AGENTS.md — no truncation, no duplication; .creed/skills/*.md remain the single authoritative source.
  • Checked name-collision hazard against real consumers: Hydra/Iris config names (context, development, workflow) don't collide with the new org entries (org, architecture, implementation, review); layered merge semantics (layer order, last-wins by name) verified in internal/adapters/layered/source.go.

Findings (all non-blocking):

  1. README.md is now stale — it still described the old pointer design this PR replaces. (Addressed in-PR: README updated in 9ac26ff.)
  2. Five H1 headings now appear in one rendered AGENTS.md — cosmetic; creed concatenates with --- separators by design (pre-existing).
  3. Silent-override hazard: a consumer declaring a config named architecture/implementation/review/org would last-wins-replace the org procedure. No current consumer does; inherent to the config-entry approach the acceptance criteria explicitly permit.
  4. Fix is dormant until consumers re-pin (pinned-layer design, no breakage either way). Noted in the PR body.
  5. PR body must include the exact probe commands and observed result — (Addressed: PR body contains the full probe transcript.)

Goal alignment: all acceptance criteria around reachability, no dangling generated pointers, and single-source-per-procedure are met and empirically verified.


Reviewer B (glm-5.1)

Verdict: APPROVE

Goal alignment — verified by live re-execution, not just by reading the diff:

  • Rebuilt the probe from scratch: fresh Hydra clone at c524ccc, org layer pinned to the branch head, creed built from afe5dbb. Results: validate passed, sync → 1 written, second sync → 0 written, 1 skipped (idempotent), diff exit 0.
  • Consumer AGENTS.md contains the full bodies of all three procedures (byte-identical to .creed/skills/*.md sources apart from the --- separators), zero remaining .creed/skills references, and deterministic ordering: Org → Architecture → Implementation → Org Review → Hydra local context.
  • In agent-context itself: validate/sync/second-sync/diff all clean; committed AGENTS.md matches the manifest, so the render isn't stale.
  • One authoritative source per procedure preserved: files under .creed/skills/ untouched; only their manifest declaration moved from skills: to config:.

Findings (non-blocking):

  1. README was stale and contradicted the PR — (Addressed in-PR: 9ac26ff.)
  2. Probe commands/results must be in the PR body — (Addressed.)
  3. Documented tradeoff: demoting the files from skills: to config: means a future skill-directory target would not emit them as discrete files — inline-only. Sanctioned by the issue for the current agents-only setup.
  4. "below" pointers are order-dependent: hold for the agents target (verified), would dangle under a hypothetical future target rendering org.md alone. Same scope caveat as docs: codify public release authority (COD-451) #3.
  5. Minor: multiple H1s — pre-existing creed join behavior, not a regression.

Nothing breaks existing functionality: skill sources unchanged, local agents target validates and renders deterministically, consumer manifests with local skills: [] coexist cleanly with the org layer (validated live).

@shivros
shivros marked this pull request as ready for review August 27, 2026 22:01
shivros and others added 2 commits September 1, 2026 18:40
…mers

The agents target aggregates config entries only; skills render to
SkillDir outputs that target lacks. Declaring architecture,
implementation, and review procedures as config entries renders them
inline into consumer AGENTS.md, keeping one authoritative source file
per procedure while removing dangling .creed/skills/* pointers.

COD-444

Co-authored-by: Archon <archon@purelymail.com>
The old text described the removed pointer design and pre-layered
consumption status. Documents the shipped layered-source design and
the config-entry rendering this branch introduces.

COD-444

Co-authored-by: Archon <archon@purelymail.com>
@shivros
shivros force-pushed the runner/COD-444-skills-reachable-config branch from 9ac26ff to 1f5700f Compare September 2, 2026 00:40
@shivros
shivros merged commit 66d135d into main Sep 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant