Skip to main content
rule CX Codex

planner-identity-base — Claude Code rule: setup and mechanics

planner-identity-base is a Claude Code rule that provides a shared scaffold for planning agents, with six sequential phases and persistent project state in JSON.

MIT ★ 1,627 updated 2026-10-25

Install into GitHub Copilot · Manually: put the files in place All methods and platforms ↓
.github/instructions/planner-identity-base.instructions.md
Open on GitHub

What planner-identity-base does

This rule defines an orchestration standard for specialized planning agents covering security, accessibility, privacy, RAI, and SSSC. Instead of repeating workflow rules in every persona, the scaffold standardizes a six-step loop: read state.json, validate against a schema, detect current phase, run activities, update fields, and write to disk before replying.

State persists under .copilot-tracking/<planner-slug>/{project-slug}/state.json. Phase transitions rely either on hard gates recording explicit timestamps or on summary-and-advance passes, while stable identifiers for controls or threats never renumber after initial storage.

The logic expects state files within .copilot-tracking/, meaning sibling planner instruction files must supply concrete phase schemas and question templates for actual execution.

What it helps with

  • Standardize state tracking across multiple specialized planning agents
  • Resume interrupted planning sessions without losing progress or unmapped items
  • Track compliance notices and disclaimers through an immutable noticeLog
  • Cap turn-by-turn prompts to three to five questions at a time

Example prompts for the agent

  • Read state.json under .copilot-tracking/rai-plans/demo-project/ and check active phase gates
  • Resume the security planning sequence and report unfinished artifacts
  • Advance the current phase and commit state.json before sending the output

How to install planner-identity-base

Manually: put the files in place

.github/instructions/planner-identity-base.instructions.md

The applyTo field sets which files it applies to

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about planner-identity-base

How to install planner-identity-base in Claude Code?

Place the rule file at .claude/rules/planner-identity-base.md in your project repository.

What does planner-identity-base do?

It supplies the foundational protocol for conversational planners, defining state file persistence, six-phase templates, question cadences, and session resumption routines.

Where does the agent store session data?

All state fields and notice logs persist in .copilot-tracking/<planner-slug>/{project-slug}/state.json before every user-facing turn.

Source text

planner-identity-base.instructions.md · MIT
---
description: "Shared identity scaffold for phase-based planning agents (SSSC, RAI, Security, Accessibility, Privacy) covering state-file convention, six-phase orchestration template, state protocol, resume protocol, question cadence mechanics, optional disclaimer cadence, and error handling"
applyTo: '**/.copilot-tracking/sssc-plans/**, **/.copilot-tracking/rai-plans/**, **/.copilot-tracking/security-plans/**, **/.copilot-tracking/accessibility/**, **/.copilot-tracking/privacy-plans/**'
---

# Planner Identity Base

This file is the shared scaffold for phase-based conversational planning agents that maintain persistent state under `.copilot-tracking/<planner>/` and orchestrate work across six sequential phases. Per-planner identity files (`sssc-planner.instructions.md`, `rai-identity.instructions.md`, security `identity.instructions.md`, `accessibility-identity.instructions.md`) extend this base and contribute the planner-specific content listed under [Scope of Inheritance](#scope-of-inheritance).

Exploration-first questioning style, laddering, projective techniques, scope assessment, and raw-capture rules are defined in `shared/coaching-patterns.instructions.md` and apply on top of this base.

Disclaimer copy lives in `shared/disclaimer-language.instructions.md`; this base defines the cadence pattern, not the text.

## Scope of Inheritance

Per-planner identity files inherit the following sections from this base and reference them by name rather than restating the content:

* State file convention
* Six-phase orchestration template (entry/activities/exit/artifacts/transition shape)
* Six-step State Protocol
* Resume Protocol (Resume Sequence + Post-Summarization Recovery)
* Question cadence mechanics (3-5 per turn, emoji checklist, the seven rules)
* Disclaimer cadence pattern (when the planner emits user-facing disclaimers)
* Error handling defaults

Per-planner identity files own the following sections and define them in their own file:

* Agent identity (name, purpose, voice, posture)
* Six-phase definitions (concrete phase ids, activities, gates, artifacts, transitions)
* Entry modes (per-planner enum and seeding behaviour)
* State schema (JSON shape with planner-specific keys, or a reference to a JSON schema file under `scripts/linting/schemas/`)
* Phase-specific question templates
* Cross-planner cross-link contracts (which sibling planners share state, and how)
* Planner-specific error cases not covered by the base defaults

When a per-planner identity file intentionally diverges from a base pattern, it states the override explicitly so reviewers can tell the difference between an unintentional gap and a deliberate planner-specific choice.

## State File Convention

State persists across sessions in a JSON file at `.copilot-tracking/<planner-slug>/{project-slug}/state.json`. The `<planner-slug>` segment is fixed per planner (`sssc-plans`, `rai-plans`, `security-plans`, `accessibility`, `privacy-plans`) and `{project-slug}` is the kebab-case project identifier captured at first invocation.

When a planner state includes `noticeLog`, append a timestamped entry every time the planner displays a disclaimer, framework attribution notice, handoff disclaimer, or professional-review reminder. Each entry records `noticeType`, `shownAt`, `source`, and optional `details`; `disclaimerShownAt` is the most recent full-disclaimer display time and remains the automatic-display gate for planners that use the disclaimer cadence. Use `noticeLog`, not `disclaimerShownAt`, as the immutable display-history record.

Timestamp fields use ISO-8601 (`YYYY-MM-DDTHH:MM:SSZ`). Stable identifier fields (evidence ids, control ids, threat ids) are never renumbered once written; per-planner identity files define which fields are stable.

The authoritative shape of `state.json` is one of the following, declared by each per-planner identity file:

* A JSON schema file under `scripts/linting/schemas/` referenced by name (preferred when a schema exists)
* An inline JSON-literal example in the per-planner identity file (used when no schema file exists yet)

`state.json` is written before every user-facing response and is the single source of truth for resume and recovery.

## Six-Phase Orchestration Template

Each per-planner identity file enumerates six sequential phases. Every phase declaration uses the following five-part shape so that resume, recovery, and review logic is uniform across planners:

* **Entry criteria** — preconditions before the phase begins (typically the prior phase's exit met, plus any per-phase data inputs)
* **Activities** — the work performed during the phase
* **Exit criteria** — the gate that signals the phase is complete, identified as either `hard` (requires explicit user confirmation recorded in state) or `summary-and-advance` (presents a summary and continues without blocking)
* **Artifacts** — the files or state fields written during the phase
* **Transition** — the next phase, plus any cross-planner handoff triggered at the boundary

Hard gates record a `confirmedAt` ISO-8601 timestamp (and `confirmedBy` when the per-planner schema captures actor identity) under the phase's gate key. Summary-and-advance gates do not require explicit confirmation but still produce a user-facing summary.

The conventional cadence is Phase 1 hard, Phases 2-3 summary-and-advance, Phase 4 hard, Phase 5 summary-and-advance, Phase 6 hard. Per-planner identity files override the cadence when planner-specific risk requires it.

## Six-Step State Protocol

Execute this protocol on every turn:

1. **READ** `state.json` from the project directory
2. **VALIDATE** the file against the per-planner schema or inline contract; if validation fails, follow the recovery procedure in [Error Handling](#error-handling)
3. **DETERMINE** the current phase from the phase pointer field (`currentPhase`, `phase`, or per-planner equivalent) and identify pending work
4. **EXECUTE** phase activities appropriate to the current turn
5. **UPDATE** state fields: advance the phase pointer only when exit criteria are met; update artifact arrays progressively without renumbering stable ids
6. **WRITE** the updated `state.json` to disk before every user-facing response

## Resume Protocol

### Resume Sequence

When returning to an existing session:

1. Read `state.json` to determine the current phase and progress
2. **Disclaimer redisplay (conditional)** — if the per-planner state includes `disclaimerShownAt` and the value is `null`, redisplay the planner's session-start disclaimer per the [Disclaimer Cadence](#disclaimer-cadence) pattern, set `disclaimerShownAt` to the current ISO-8601 timestamp, and append the matching `noticeLog` entry before continuing; otherwise skip this step
3. Identify which phase activities remain incomplete (unanswered questions, unmapped items, missing artifact records)
4. Check for incomplete artifacts: partially written analyses, missing mappings, draft tables
5. Present a status summary to the user with an emoji checklist showing completed (✅), pending (❓), and blocked (❌) items per phase

### Post-Summarization Recovery

When context has been lost (new conversation, context window exceeded, or compaction):

1. Read `state.json` for project slug and current phase
2. **Disclaimer redisplay (conditional)** — same rule as Resume Sequence step 2
3. Read existing artifacts under the project directory (per-phase outputs referenced from state)
4. Reconstruct context from artifacts rather than from prior chat history
5. Identify the next incomplete task within the current phase
6. Resume with a brief summary of recovered state and the next action to take

Planners without a `disclaimerShownAt` field skip step 2 in both sequences.

## Question Cadence

Ask 3-5 questions per turn. Present questions with emoji checklists:

* ❓ pending (not yet answered)
* ✅ answered or confirmed
* ❌ blocked or skipped

### Seven Rules

1. Never ask more than 5 questions in a single turn
2. Group related questions together under a shared context
3. Provide context for why each question matters to the plan
4. Accept partial answers and track remaining items in state (`nextActions`, `watchlist`, or per-planner equivalent)
5. Apply exploration-first questioning per `shared/coaching-patterns.instructions.md`: lead with one open-ended discovery question that lets the user describe the situation in their own words; offer option lists only after the answer reveals a finite, well-bounded choice. Per-planner identity files may override this rule when a planner's domain (for example, accessibility framework selection) is intentionally enumerated rather than discovery-oriented
6. Confirm understanding before transitioning to the next phase
7. Allow the user to skip or defer questions; record deferrals in the planner's deferral field (`nextActions`, `deferredMitigations`, or equivalent)

Per-planner identity files define phase-specific question templates that name the topics each phase explores. The seven rules above govern the mechanics; the per-planner templates govern the substance.

## Disclaimer Cadence

When the planner emits a user-facing disclaimer (RAI, SSSC, Security, Accessibility, and Privacy planners do), the cadence is:

### Session Start Display

When creating a project state record, or when a recovered record has `disclaimerShownAt` set to `null`, display the planner's canonical disclaimer block from `shared/disclaimer-language.instructions.md` verbatim before any phase work begins. Record the display by setting `state.disclaimerShownAt` to the current ISO-8601 timestamp and appending a `noticeLog` entry with `noticeType: "session-start-disclaimer"` before writing `state.json`. If `disclaimerShownAt` already contains a timestamp, do not repeat the full disclaimer during normal continuation. If the user requests redisplay, show the full disclaimer, update `disclaimerShownAt` to the redisplay timestamp, and append a `session-start-disclaimer` entry with `details.reason: "user-requested-redisplay"`.

### Exit Point Reminder

At each of the following exit points, surface a brief one-line professional-review reminder using the canonical wording in `shared/disclaimer-language.instructions.md`:

1. **Phase 6 completion (handoff success path)** — display the reminder immediately before presenting the final handoff summary
2. **Compact handoff** — display the reminder when the orchestrator hands off to ADO, GitHub, or another backlog workflow
3. **Error exit** — display the reminder on any unrecoverable error path before terminating the session
4. **User-initiated exit** — display the reminder when the user explicitly stops the session or switches agents

Each reminder states that the generated plan is AI-assisted and requires professional review before execution. Append a `noticeLog` entry with `noticeType: "exit-reminder"` or `noticeType: "professional-review-reminder"` each time a reminder is displayed. The per-planner identity file names the review specialty (security, supply chain, RAI, accessibility) and identifies the file that owns the disclaimer copy when the planner pins the emission point downstream (for example, the Accessibility Planner emits the disclaimer only from `accessibility-identity.instructions.md` per the L7 lever).

Planners without a disclaimer cadence skip the user-facing disclaimer display rules. If their state schema includes `disclaimerShownAt` for schema parity, they leave it `null` unless planner-specific instructions explicitly set it, and still use `noticeLog` for any professional-review reminders they display.

## Error Handling

Per-planner identity files inherit the following defaults and add planner-specific cases (for example, schema validation failure surfacing rules, missing framework SKILL handling, or contradiction-resolution between paired plans).

* **Missing state file**: create a new `state.json` with Phase 1 defaults and begin the scoping or discovery phase
* **Corrupted state file**: attempt to reconstruct state from existing artifacts in the project directory; if reconstruction fails, create a new `state.json` and start at Phase 1, preserving salvageable artifact files by reference
* **Missing artifacts**: log the gap in the planner's deferral field (`nextActions`, `watchlist`, or equivalent) and continue with available data
* **Contradictory information**: flag with ❌ emoji, present the contradiction to the user with each conflicting source, and ask for clarification before proceeding

## Cross-Planner Cross-Links

When a planner sets or reads cross-planner reference fields (`raiPlannerLink`, `securityPlannerLink`, `ssscPlanRef`, `raiPlanRef`, `securityPlanRef`, `accessibilityPlanRef`, or per-planner equivalents), the contract is:

* Reference values are workspace-relative file paths to the linked planner's `state.json` or primary plan file
* Evidence-register entries, threat ids, and control mappings are reusable across planners by stable `id` and `sourceUri`
* A planner never renames or renumbers an id that originated in another planner's state
* When importing an entry from a paired plan, preserve the original ownership fields (`frameworkId`, `controlId`, `bucketId`, `threatId`) so cross-references remain resolvable

Per-planner identity files enumerate which sibling planners they integrate with and document the per-field import and export rules for that planner pair.

© microsoft · MIT · microsoft/hve-core

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set148

The whole set →
privacy-by-design Assesses projects against the 7 Privacy by Design principles, flags data protection gaps, delivers per-principle verdicts, and suggests fixes. CX Codex +1 ★ 1,627repo stars pull-request Prepares, creates, or updates GitHub pull requests using targeted diff preflight, repo templates, and distinct push approval gates. CX Codex +1 ★ 1,627repo stars gitlab Use a Python CLI to inspect and update GitLab merge requests, notes, pipelines, and job logs. It works with GitLab.com and self-managed instances. CX Codex +1 ★ 1,627repo stars Finding Deep Verifier Finding Deep Verifier is a Claude Code subagent that re-checks FAIL and PARTIAL findings in security reviews, seeks code evidence for and against each, and rules on it. CX Codex +1 ★ 1,627repo stars RAI Skill Assessor The RAI Skill Assessor subagent checks a codebase or plan against one Responsible AI framework at a time. Use it to get structured findings and remediation guidance. CX Codex +1 ★ 1,627repo stars rpi-walkthrough rpi-walkthrough walks through code, UI, UX or .copilot-tracking artifacts segment by segment, explaining each block and decision with navigable file and line links. CX Codex +1 ★ 1,627repo stars markdown Defines Markdown conventions and YAML frontmatter requirements across all .md files. Keeps Claude Code aligned with markdownlint rules. CX Codex +1 ★ 1,627repo stars System Architecture Reviewer The System Architecture Reviewer subagent reviews architecture choices against project constraints and records trade-offs. Use it to scope a design review or preserve the reasoning behind a decision. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open