Agent Architecture

Architecture Diagram

flowchart TD
  subgraph Agent ["RAI Planner Agent"]
    RP["rai-planner.agent.md"]
    RS["Researcher Subagent"]
    RP -->|"delegates framework lookups"| RS
  end

  subgraph State ["Assessment State"]
    SJ["state.json"]
    AF["Phase Artifacts"]
    SJ -->|"references"| AF
  end

  subgraph Instructions ["Instruction Files"]
    I1["rai-identity"]
    I2["rai-license-posture"]
  end

  subgraph Skills ["Skills"]
    S1["rai-planner"]
    S2["rai-standards"]
  end

  RP -->|"reads/writes"| SJ
  RP -->|"generates"| AF
  RP -->|"follows"| I1
  RP -->|"follows"| I2
  RP -->|"uses"| S1
  RP -->|"uses"| S2

The RAI Planner agent definition lives at .github/agents/rai-planning/rai-planner.agent.md. Two instruction files under .github/instructions/rai-planning/ provide domain-specific guidance, auto-applied via applyTo patterns when working within .copilot-tracking/rai-plans/. Phase-specific assessment guidance lives in the shared backlog-templates skill and the rai-standards skill.

Instruction file	Domain
rai-identity.instructions.md	Agent identity, orchestration, state management, session recovery
rai-license-posture.instructions.md	RAI standards licensing posture, source-class mapping, attribution gating

Skill	Domain
rai-planner	Risk classification, impact assessment, security model, capture coaching, and backlog handoff phase references
rai-standards	NIST AI RMF 1.0 trustworthiness characteristics, subcategory mappings, framework isolation, AI STRIDE overlay

State Management

All assessment state persists under .copilot-tracking/rai-plans/{project-slug}/. The state.json file tracks phase progress, entry mode, and assessment metadata.

State Fields

Field	Type	Purpose
projectSlug	string	Kebab-case project identifier
raiPlanFile	string	Path to the RAI plan markdown file
currentPhase	number	Current phase (1-6)
entryMode	string	capture, from-prd, or from-security-plan
disclaimerShownAt	string or null	ISO 8601 timestamp when the disclaimer was displayed
securityPlanRef	string or null	Path to security plan state when using from-security-plan
assessmentDepth	string	Assessment tier (Basic, Standard, or Comprehensive)
riskClassification	object	Phase 2 risk classification results including suggestedDepthTier
standardsMapped	boolean	Whether Phase 3 mapping is complete
securityModelAnalysisStarted	boolean	Whether Phase 4 analysis has begun
raiThreatCount	number	Running count of identified RAI threats
impactAssessmentGenerated	boolean	Whether Phase 5 assessment is complete
evidenceRegisterComplete	boolean	Whether evidence register is finalized
handoffGenerated	object	Dual-format handoff status ({ "ado": false, "github": false })
gateResults	object	Gate outcomes for threat coverage
runningObservations	array	Cross-phase observation log with phase number, observation text, and flag level
principleTracker	object	Per-principle coverage status, threat counts, and open observations
referencesProcessed	array	Files that have been read and incorporated
nextActions	array	Pending action items for the current phase
signingRequested	boolean	Whether artifact signing was requested
signingManifestPath	string or null	Path to the signing manifest file
userPreferences	object	User-specified preferences for interaction and output

Six-Step State Protocol

Every conversation turn follows this protocol:

Step	Action	Description
1	READ	Load state.json at conversation start
2	VALIDATE	Confirm state integrity and check for missing fields
3	DETERMINE	Identify current phase and next actions from state
4	EXECUTE	Perform phase work (questions, analysis, artifact generation)
5	UPDATE	Update state.json with results
6	WRITE	Persist updated state.json to disk

Interaction Model

The agent asks up to 7 focused questions per turn, using emoji checklists to track progress within each phase.

Marker	Meaning
❓	Pending: question not yet answered
✅	Complete: answer received and recorded
❌	Blocked or skipped: user indicated "skip" or "n/a"

Each turn begins by showing the current phase checklist status. When all questions for a phase reach ✅ or ❌, the agent summarizes findings. At hard gates (Phases 2, 3, and 6) it then asks for explicit confirmation before advancing; at summary-and-advance gates (Phases 1, 4, and 5) it advances unless the user objects.

NOTE

Phases 2, 3, and 6 are hard gates that require explicit user confirmation before advancing. Phases 1, 4, and 5 are summary-and-advance gates: the agent presents a summary and advances unless the user objects. This keeps the user in control at the decision points that carry irreversible downstream effect while keeping lighter phases moving.

Session Resume Protocol

When returning to an existing RAI assessment, the agent follows a five-step resume protocol:

1. Read state.json from the project slug directory
2. If disclaimerShownAt is null, display the Startup Announcement verbatim and record the timestamp
3. Display current phase progress and checklist status
4. Summarize what was completed and what remains
5. Continue from the last incomplete action

Post-Summarization Recovery

When conversation context is compacted, a six-step recovery process reconstructs state:

1. Read state.json for project slug and current phase
2. If disclaimerShownAt is null, display the Startup Announcement verbatim and record the timestamp
3. Read the RAI plan markdown file referenced in raiPlanFile
4. Reconstruct context from existing artifacts (system definition pack, standards mapping, security model addendum, and control surface catalog)
5. Identify the next incomplete task within the current phase
6. Resume with a brief summary of recovered state and the next action

NOTE

The disclaimer and attribution notices described above are conversational, displayed in the chat interface during session starts, resumes, and exit points. Generated artifacts in Phases 5 and 6 carry separate persisted footers (AI-content transparency notes, human review checkboxes, and full disclaimers on handoff deliverables) written directly into the markdown files. See Handoff Pipeline for details on persisted artifact footers.

Operational Constraints

• All files are created under .copilot-tracking/rai-plans/{project-slug}/
• The agent never modifies application source code
• Embedded standards (NIST AI RMF 1.0) are referenced from the rai-standards instruction file
• Additional framework lookups (WAF, CAF, ISO 42001, EU AI Act details) are delegated to the Researcher Subagent
• In from-security-plan mode, security plan artifacts are read-only

Related Files

File	Purpose
.github/agents/rai-planning/rai-planner.agent.md	Agent definition
.github/instructions/rai-planning/*.instructions.md	Phase-specific instruction files
.github/prompts/rai-planning/rai-capture.prompt.md	Capture mode entry prompt
.github/prompts/rai-planning/rai-plan-from-prd.prompt.md	PRD-seeded entry prompt
.github/prompts/rai-planning/rai-plan-from-security-plan.prompt.md	Security plan-seeded entry prompt
.copilot-tracking/rai-plans/{project-slug}/state.json	Assessment state

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.