docs: Add agent-compatible code problem document - #1
Conversation
30b0239 to
3e415b1
Compare
|
I think my only question here is:
|
b88a987 to
a7ef7e5
Compare
|
Good question. I considered both options earlier today. repo-readiness.md is diagnostic — it describes current state (coverage tables, CI maturity) and asks what needs to improve before agents can be trusted. Language choice is prescriptive — it defines properties that new code should have. Expanding repo-readiness to include language guidance changes the character of that document. The topic cross-cuts beyond readiness. Type safety reduces agent drift (security-threat-model.md), simplifies code review by offloading categories of checks to the compiler (code-review.md), and enables boundary typing for consumed dependencies like hermeto — a concern that doesn't exist in repo-readiness at all. Folding it into repo-readiness would either force that doc to absorb concerns from other domains or require the language guidance to be artificially narrow. I applied the same reasoning when creating codebase-context.md (merged in #3) — that topic also cross-cuts review, drift, invariants, and readiness without fitting cleanly into any single existing doc. That said, repo-readiness.md could reference agent-compatible-code.md as a related concern — the way it already references CLAUDE.md as a readiness criterion. Happy to add that cross-link if it helps. |
|
Yeah, I like the cross link! Thanks! |
No existing problem document addresses what properties of code make it suitable for autonomous agent operation. This is distinct from repo-readiness (which is diagnostic) and architectural-invariants (which derives from the architecture repo). The new document defines criteria-based language selection (static type checking, error locality, refactoring safety, tooling, deployment simplicity) without prescribing specific languages. It distinguishes between in-house code (which should meet the criteria) and consumed dependencies (where the requirement shifts to typed integration boundaries), using hermeto/cachi2 as a concrete example. Assisted-by: Claude Code (Opus 4.6) Signed-off-by: arewm <arewm@users.noreply.github.com>
a7ef7e5 to
8188963
Compare
|
Done! 😄 |
Seven specialized agents for working on the fullsend project: - fullsend-architect (opus): architectural coherence guardian; knows all ADRs, five execution layers, story dependencies, repo-as-coordinator invariant - go-developer (sonnet): CLI specialist; forge abstraction, layered config, multi-role GitHub App model, known gaps in PR #132 - doc-architect (sonnet): problem doc and ADR writer; design-exploration conventions, org-agnostic authoring rules - stage-prompt-designer (opus): designs/reviews stage agent prompts; triage/implement/review/fix constraints, injection surface rules, known failure modes from live operation (Issues #4, #5, #010a) - security-reviewer (opus): applies fullsend threat model; prompt injection, ADR 0017 credential isolation, sandbox integrity, workflow file protection - workflow-engineer (sonnet): GitHub Actions and dispatch layer; label state machine, slash commands, concurrency groups, fixes for Issues #1 #003b #4 #5 #7 #9 #010a - e2e-integrator (opus): full flow tracing; integration gap analysis, demo readiness checklist, sprint prioritization across stories Also adds .claude/AGENTS.md with usage guide and team composition patterns.
2 participants
Summary
No existing problem document addresses what properties of code make it suitable for autonomous agent operation. This is distinct from repo-readiness (which is diagnostic) and architectural-invariants (which derives from the architecture repo).
The new document defines criteria-based language selection (static type checking, error locality, refactoring safety, tooling, deployment simplicity) without prescribing specific languages. It distinguishes between in-house code (which should meet the criteria) and consumed dependencies (where the requirement shifts to typed integration boundaries), using hermeto/cachi2 as a concrete example.
Assisted-by: Claude Code (Opus 4.6)