ietf-draft-analyzer/workspace/draft-team/AGENTS.md

Follow this workflow for all work in this repository.

Goal

Produce publication-ready IETF draft packages from existing ietf-draft-analyzer data with minimal token use and strong role separation.

Roles

• researcher: synthesize current evidence, identify missing evidence, and propose follow-up investigation
• architect: convert research into a precise spec strategy and section plan
• author: write the draft from the approved architecture
• security-reviewer: find protocol, trust, abuse, privacy, and threat-model flaws
• software-reviewer: find implementability, state-machine, testing, and operational gaps
• architecture-reviewer: find scope drift, internal inconsistency, and design weakness
• ietf-senior-reviewer: find IETF process, document-shape, terminology, and publishability issues
• review-lead: synthesize specialist reviews into one prioritized revision plan

Token Discipline

• Read the current cycle files first, not the whole repository.
• Prefer references/analyzer-integration.md to rediscovering source locations.
• Load only the specific analyzer outputs needed for the current question.
• Keep handoff files short, factual, and structured.
• Reuse filenames and templates; avoid free-form notes outside the cycle folder.

Cycle Files

Each cycle lives in cycles/<slug>/ and uses these files:

• 00-user-spec.md: user intent, constraints, success criteria
• 10-research-brief.md: evidence summary, gaps, new data to fetch
• 20-architecture-brief.md: scope, design, requirements, risks, outline
• 30-outline.md: draft outline and section-level writing guidance
• 40-draft-v1.md: first full draft
• 50-reviews-v1/: specialist review folder
• 55-review-synthesis-v1.md: merged findings and priority order
• 60-revision-plan-v1.md: concrete changes for next draft

Continue with v2, v3, and so on.

Operating Rules

• Do not skip the architecture step before drafting.
• Do not let the author invent core requirements that are absent from the research or architecture brief.
• Do not let specialist reviewers rewrite the whole draft when targeted changes are sufficient.
• Escalate contradictions between user specs, research evidence, and draft text.
• Track assumptions explicitly.
• Treat Security Considerations, Privacy Considerations, and IANA Considerations as first-class work items.
• Prefer parallel specialist review after each draft, then one synthesis pass.

Done Criteria

A draft is ready for user sign-off only when:

• the architecture brief and the draft agree on scope
• major claims are backed by cited evidence or marked as hypotheses
• open issues are either resolved or explicitly listed
• specialist review findings are addressed or consciously deferred
• publishability risks are called out plainly