Claude Code GitHub Actions flow for durable agent memory, manager repos, and Sleeping issue audits

AGENTS.md

Project Management Flow for Agentic Work

Use this prompt as the standing operating guidance for any AI-assisted project, regardless of the specific chat tool, agent runtime, issue tracker, or automation platform.

The goal is simple: every execution should leave behind enough durable project state that a future agent or human can understand what exists, what changed, what remains open, and how to continue without depending on hidden chat history.

Related guidance:

• MANAGER.md: use when a domain spans multiple repositories, teams, channels, queues, or workflows.
• SLEEPING.md: use for scheduled consistency checks between durable memory and the real project/runtime state.

Core Principle

Treat chat threads, agent sessions, task runs, and conversation history as soft state.

Durable recovery context must live in the project repository, or in a clearly identified manager repository when the work spans multiple repositories.

Every project should be able to answer these questions from files:

• What is this project?
• What is the current runtime/product state?
• What decisions have already been made?
• What commands install, test, deploy, verify, back up, and restore it?
• What other systems does it depend on?
• What tasks are open, blocked, scheduled, or recently completed?
• How should another agent safely continue the work?

Required Repository Memory

Every repository touched by an agent must have:

AGENTS.md
docs/agent/STATE.md
docs/agent/RUNBOOK.md
docs/agent/DECISIONS.md
docs/agent/LINKED_REPOS.md

If these files do not exist, create them before or during the first meaningful change.

Keep them concise. They are not diaries. They are operational memory.

AGENTS.md

Purpose: standing instructions for agents working in this repository.

Include:

• project boundaries and ownership
• commands and conventions that are always relevant
• safety rules
• commit/deploy expectations
• where durable state lives
• what should not be committed

docs/agent/STATE.md

Purpose: current project state.

Update when:

• product/runtime behavior changes
• active priorities change
• known issues are discovered or resolved
• deployed state differs from local assumptions
• a new subsystem becomes important

Include:

• current status
• active priorities
• known issues
• latest verified runtime facts
• recent important changes

docs/agent/RUNBOOK.md

Purpose: operational commands.

Update when commands or procedures change for:

• install
• local development
• tests
• type checks and linting
• deploys
• live health checks
• logs and debugging
• cron/scheduled jobs
• backup and restore
• migrations

Prefer exact commands over prose.

docs/agent/DECISIONS.md

Purpose: durable architectural and product decisions.

Update when a decision should survive the current chat/session.

Each decision should include:

• date
• decision
• context
• consequences
• alternatives considered, when useful

docs/agent/LINKED_REPOS.md

Purpose: cross-repository contracts.

Update when the project depends on another repository, service, queue, database, API, worker, package, deployment, or shared schema.

Include:

• repo/service name
• local path, if known
• remote URL, if known
• ownership boundary
• contract or dependency
• live route, queue, bucket, database, or hostname, when relevant

Execution Loop

For every non-trivial task:

1. Read AGENTS.md.
2. Read relevant docs/agent/*.
3. Inspect the actual code/runtime before assuming.
4. Make the smallest coherent change.
5. Verify with the most authoritative check available.
6. Update durable docs when the project state, commands, decisions, or dependencies changed.
7. Commit and push, if the project workflow expects versioned completion.
8. Leave a short completion note with:
   • what changed
   • what was verified
   • what remains open
   • where the durable state was updated

Verification Standard

Prefer evidence from the real system:

• tests
• type checks
• live health endpoints
• logs
• database queries
• deployment metadata
• screenshots
• API responses
• CI runs
• user confirmation for human tasks

Do not mark work complete only because code was edited.

Recovery Standard

A new agent should be able to continue from:

1. the repository files
2. the manager repository, if one exists
3. the issue/work-item queue
4. the latest verified runtime state

If hidden chat history is required to understand the project, the flow has failed. Move the needed knowledge into durable files.

What Not To Persist

Do not commit:

• secrets
• tokens
• private keys
• raw chat transcripts
• raw uploaded files unless explicitly intended
• credentials in remotes
• unnecessary personal data
• noisy run logs
• large generated artifacts without a reason

Persist summaries, evidence, and operational facts instead.

Minimal Repository Bootstrap

When bootstrapping a repository, create:

AGENTS.md
docs/agent/STATE.md
docs/agent/RUNBOOK.md
docs/agent/DECISIONS.md
docs/agent/LINKED_REPOS.md

AGENTS.md belongs at the root of the repository. The durable memory files belong under docs/agent/.

Root AGENTS.md Starter

# Agent Instructions

This repository uses durable agent context under `docs/agent/`.

Before making non-trivial changes, read:

- `docs/agent/STATE.md`
- `docs/agent/RUNBOOK.md`
- `docs/agent/DECISIONS.md`
- `docs/agent/LINKED_REPOS.md`

Keep those files current whenever project state, commands, decisions, or cross-repo contracts change.

Treat chat/session history as soft state. Durable recovery context belongs in this repo or its manager repo.

docs/agent/STATE.md Starter

# State

Current status: unknown.

## Active Priorities

- none recorded

## Known Issues

- none recorded

## Latest Verified Runtime Facts

- none recorded

docs/agent/RUNBOOK.md Starter

# Runbook

## Install

- not documented yet

## Test

- not documented yet

## Deploy

- not documented yet

## Verify

- not documented yet

docs/agent/DECISIONS.md Starter

# Decisions

No durable decisions recorded yet.

docs/agent/LINKED_REPOS.md Starter

# Linked Repositories and Services

No linked repositories or services recorded yet.

One-Sentence Rule

If a future agent would need to know it to continue safely, write it into the repo or the manager repo before you finish.

MANAGER.md

Manager Repository Pattern

Use this guidance when a domain spans multiple repositories, teams, channels, queues, automations, or workflows.

A manager repository is the control plane. It does not replace repo-local memory; it centralizes coordination and recovery for a wider domain.

Examples:

• company manager
• product manager
• household/life manager
• infrastructure manager
• customer support manager
• marketing manager

Core Responsibilities

A manager repository should answer:

• Which repositories, services, or workflows belong to this domain?
• What is the current status of each?
• Which work items are open, blocked, scheduled, or complete?
• Which scheduled jobs exist?
• Which repos are missing durable memory?
• Which systems depend on each other?
• How would a new agent reconstruct the fleet from durable files?

Recommended Files

AGENTS.md
README.md
fleet.json
docs/agent/STATE.md
docs/agent/RUNBOOK.md
docs/agent/DECISIONS.md
docs/agent/LINKED_REPOS.md
docs/repo-status.md
docs/repo-status.json
docs/repo-memory/INDEX.md
docs/work-items.md
docs/cron.md
docs/sleeping.md
snapshots/latest.json

fleet.json

Purpose: machine-readable inventory of managed repositories and workspaces.

Track:

• name
• local path
• remote URL
• default branch
• owner/domain
• manager topic/channel/queue, if any
• agent state path
• runbook path
• health checks
• deploy target
• linked repos

docs/repo-status.*

Purpose: generated or manually maintained summary of the fleet.

Track:

• branch
• latest commit
• dirty state
• missing required docs
• known topic/channel binding
• open work items
• latest verification result

docs/repo-memory/INDEX.md

Purpose: cross-repo notes that do not belong cleanly inside one component repository.

Keep this file short and index-like. Prefer repo-local docs/agent/* for facts owned by one repo.

docs/work-items.md

Purpose: durable task queue when no external tracker is authoritative.

Each item should include:

• id
• title
• status: open, active, blocked, done
• owner: human, agent, team, unknown
• priority
• target repo
• evidence required for completion
• due date or revisit date, if any

Work items are not reminders in chat. They must be persisted.

Use work items for:

• follow-ups
• blocked tasks
• delegated human work
• scheduled checks
• audits
• recurring operational duties
• cross-repo coordination

Every work item needs completion evidence. Examples:

• test command passed
• deploy URL checked
• health endpoint returned expected metadata
• human confirmed completion
• file was created
• issue was closed
• payment was received
• document was signed

docs/cron.md

Purpose: scheduled agent or automation work.

Track:

• schedule
• target project
• prompt/task
• expected evidence
• last run
• next run
• failure policy

Scheduled agents should wake up with a bounded task and a place to write results.

Every scheduled job should define:

• scope
• schedule
• repository or manager repository
• prompt/task
• expected evidence
• max runtime or budget
• failure reporting location
• whether it may commit/push

Scheduled jobs should update durable state, not just send a message.

Snapshots

Use snapshots for sanitized operational state that helps reconstruct the system.

Snapshots may include:

• manager inventory
• repo status
• topic/channel/queue bindings
• work items
• scheduled jobs
• health check results
• deployment metadata

Snapshots should not include:

• secrets
• tokens
• raw chat transcripts
• unnecessary personal data
• noisy logs

Manager Execution Loop

For manager-level work:

1. Read the manager AGENTS.md.
2. Read manager docs/agent/*.
3. Refresh or inspect the fleet inventory.
4. Route repo-specific facts back to the repo that owns them.
5. Keep cross-repo facts in the manager repo.
6. Persist work items instead of relying on chat reminders.
7. Verify status from real repos and runtime evidence when available.
8. Commit and push manager changes when the workflow expects versioned completion.

Manager Rule

The manager repo centralizes coordination. The component repos remain the source of truth for their own implementation and operational memory.

SLEEPING.md

Sleeping

Sleeping is a scheduled maintenance mode where an agent wakes up without a new user request and verifies that durable project memory is still consistent with the real repository and runtime.

The purpose is not to do open-ended work. The purpose is to detect drift, repair small documentation mismatches, and create durable work items for anything that needs human or deeper agent attention.

Sleeping should usually run daily for active projects and less frequently for stable projects.

docs/sleeping.md

Purpose: daily or periodic consistency checks between durable memory and reality.

Track:

• repositories checked
• schedule
• memory files checked
• code/runtime facts verified
• inconsistencies found
• fixes committed
• work items opened
• latest successful sleep run
• latest failed sleep run

Sleeping Inputs

A sleeping agent should read:

• AGENTS.md
• docs/agent/STATE.md
• docs/agent/RUNBOOK.md
• docs/agent/DECISIONS.md
• docs/agent/LINKED_REPOS.md
• manager repository inventory, if one exists
• open work items
• scheduled jobs
• recent git history
• relevant deployment or runtime metadata

Sleeping Checks

During sleep, verify:

• required docs/agent/* files exist
• documented commands still exist and are plausible
• package scripts, deploy scripts, cron jobs, and health checks match the runbook
• linked repos, services, queues, databases, buckets, routes, and hostnames still match the code
• documented active priorities match open work items and recent commits
• documented known issues still appear true
• completed work items have evidence
• scheduled jobs have a clear owner, prompt, evidence target, and failure policy
• manager inventory matches local repos and remotes
• deployment metadata or health endpoints agree with documented runtime state, when live access is available

Sleeping Outputs

A sleep run should write a concise result to durable state, such as:

docs/sleeping.md
docs/agent/STATE.md
docs/work-items.md

The output should include:

• date/time
• repositories checked
• checks performed
• inconsistencies found
• files updated
• work items opened
• verification evidence
• anything skipped and why

Sleeping Repair Rules

The sleeping agent may directly fix:

• stale status notes
• missing docs/agent/ files
• outdated command references when the correct command is obvious from the repo
• missing links between manager inventory and repo-local docs
• completed work items that already have clear evidence

The sleeping agent should not silently make product, schema, deploy, billing, auth, or infrastructure changes unless explicitly authorized by the project instructions.

For larger discrepancies, create or update a work item with evidence instead of guessing.

Sleeping Prompt Template

You are running in Sleeping mode for this project.

Goal:
Verify that repo-owned durable memory is consistent with the actual repository, manager inventory, scheduled jobs, work items, and live runtime evidence available to you.

Rules:
- Treat chat history and prior agent sessions as soft state.
- Read AGENTS.md and docs/agent/* first.
- Inspect the real code, scripts, config, git history, and runtime evidence before deciding memory is correct.
- Create missing docs/agent files if they do not exist.
- Update durable docs only when you have concrete evidence.
- Do not make product, schema, deploy, billing, auth, or infrastructure changes unless explicitly authorized.
- For significant drift, open or update a durable work item instead of guessing.
- Commit and push only documentation, inventory, snapshot, or work-item changes that belong to this sleep run.

Expected output:
- A concise sleep report in docs/sleeping.md or the manager repository.
- Updated docs/agent/* when durable memory was stale.
- Work items for unresolved drift.
- A short final summary with verification evidence and remaining risk.

GitHub Actions Issue-Only Example

Use this pattern when Sleeping should run in CI and report findings as GitHub Issues, without committing changes to the branch where it ran.

This workflow intentionally grants:

• contents: read so the job can inspect the repository but cannot push changes with GITHUB_TOKEN
• issues: write so the job can open a GitHub Issue

It also uses persist-credentials: false during checkout and records any accidental file modifications in the report instead of committing them.

This Claude Code variant requires:

• ANTHROPIC_API_KEY stored as a repository or organization secret
• the Claude Code base action, anthropics/claude-code-base-action@beta

Create:

.github/workflows/sleeping.yml
.github/prompts/sleeping.md

.github/workflows/sleeping.yml

name: Sleeping

on:
  schedule:
    - cron: "17 7 * * *"
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  sleep:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      REPORT_FILE: ${{ runner.temp }}/sleep-report.md
      FINDINGS_FILE: ${{ runner.temp }}/sleep-findings.md
      OPEN_ISSUE_FILE: ${{ runner.temp }}/open-sleeping-issue
      OWNER_MENTIONS_FILE: ${{ runner.temp }}/owner-mentions.md

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Prepare sleep report
        run: |
          {
            echo "# Sleeping report"
            echo
            echo "- Repository: $GITHUB_REPOSITORY"
            echo "- Run: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
            echo "- Commit: $GITHUB_SHA"
            echo "- Started: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"
            echo
          } > "$REPORT_FILE"

      - name: Check Claude Code Sleeping prompt
        id: prompt
        run: |
          set -euo pipefail

          if [ ! -f .github/prompts/sleeping.md ]; then
            {
              echo "## Configuration issue"
              echo
              echo "- Missing .github/prompts/sleeping.md"
            } >> "$REPORT_FILE"
            touch "$OPEN_ISSUE_FILE"
            echo "exists=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "exists=true" >> "$GITHUB_OUTPUT"

      - name: Run Claude Code Sleeping audit
        if: steps.prompt.outputs.exists == 'true'
        id: claude
        uses: anthropics/claude-code-base-action@beta
        continue-on-error: true
        with:
          prompt_file: .github/prompts/sleeping.md
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          max_turns: "8"
          allowed_tools: "View,GlobTool,GrepTool,Bash(git:*),Bash(test:*),Bash(find:*),Bash(ls:*)"

      - name: Collect Claude Code findings
        if: steps.prompt.outputs.exists == 'true'
        env:
          CLAUDE_OUTCOME: ${{ steps.claude.outcome }}
          CLAUDE_RESULT: ${{ steps.claude.outputs.result }}
        run: |
          set -euo pipefail

          if [ "$CLAUDE_OUTCOME" != "success" ]; then
            {
              echo "## Sleeping agent failed"
              echo
              echo "Claude Code exited with a non-success status."
            } >> "$REPORT_FILE"
            touch "$OPEN_ISSUE_FILE"
            exit 0
          fi

          if [ -n "${CLAUDE_RESULT:-}" ]; then
            printf '%s\n' "$CLAUDE_RESULT" > "$FINDINGS_FILE"
            cat "$FINDINGS_FILE" >> "$REPORT_FILE"
          else
            {
              echo "## Findings"
              echo
              echo "No relevant findings reported by the Sleeping agent."
            } >> "$REPORT_FILE"
          fi

      - name: Add likely commit authors for affected files
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail

          python3 - <<'PY' > "$RUNNER_TEMP/affected-files.txt"
          import os
          import re
          from pathlib import Path

          report = Path(os.environ["REPORT_FILE"]).read_text()
          candidates = set()

          for value in re.findall(r"`([^`]+)`", report):
              if "/" in value or "." in value:
                  candidates.add(value.strip())

          for value in re.findall(r"\(([^)]+)\)", report):
              if "/" in value or "." in value:
                  candidates.add(value.strip())

          for candidate in sorted(candidates):
              path = Path(candidate)
              if path.exists() and path.is_file():
                  print(candidate)
          PY

          if [ ! -s "$RUNNER_TEMP/affected-files.txt" ]; then
            exit 0
          fi

          : > "$OWNER_MENTIONS_FILE"

          while IFS= read -r path; do
            logins="$(
              { gh api "repos/$GITHUB_REPOSITORY/commits" \
                --method GET \
                -F path="$path" \
                -F per_page=5 \
                --jq '.[] | .author.login // empty' 2>/dev/null || true; } \
                | sort -u
            )"

            names="$(
              git log --follow --format='%an <%ae>' -- "$path" \
                | awk '!seen[$0]++ { print }' \
                | head -5
            )"

            if [ -n "$logins" ]; then
              mentions="$(printf '%s\n' "$logins" | sed 's/^/@/' | paste -sd, - | sed 's/,/, /g')"
              echo "- \`$path\`: $mentions" >> "$OWNER_MENTIONS_FILE"
            elif [ -n "$names" ]; then
              flat_names="$(printf '%s\n' "$names" | paste -sd';' - | sed 's/;/; /g')"
              echo "- \`$path\`: $flat_names" >> "$OWNER_MENTIONS_FILE"
            fi
          done < "$RUNNER_TEMP/affected-files.txt"

          if [ -s "$OWNER_MENTIONS_FILE" ]; then
            {
              echo
              echo "## Likely commit authors for affected files"
              echo
              echo "These people recently touched files mentioned in the findings and may have useful context."
              echo
              cat "$OWNER_MENTIONS_FILE"
            } >> "$REPORT_FILE"
          fi

      - name: Record and discard accidental file changes
        run: |
          set -euo pipefail

          if [ -n "$(git status --porcelain)" ]; then
            {
              echo
              echo "## Accidental file changes detected"
              echo
              echo "Sleeping is running in issue-only mode. These changes were not committed."
              echo
              echo '```text'
              git status --short
              echo '```'
              echo
              echo "### Diff stat"
              echo
              echo '```text'
              git diff --stat
              echo '```'
            } >> "$REPORT_FILE"
            touch "$OPEN_ISSUE_FILE"

            git reset --hard
            git clean -fd
          fi

      - name: Decide whether to open an issue
        id: findings
        run: |
          set -euo pipefail

          if [ -f "$OPEN_ISSUE_FILE" ]; then
            echo "open_issue=true" >> "$GITHUB_OUTPUT"
          elif grep -q "No relevant findings reported by the Sleeping agent\\." "$REPORT_FILE"; then
            echo "open_issue=false" >> "$GITHUB_OUTPUT"
          else
            echo "open_issue=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Open issue
        if: steps.findings.outputs.open_issue == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail

          title="Sleeping findings: $(date -u +"%Y-%m-%d")"
          gh issue create \
            --repo "$GITHUB_REPOSITORY" \
            --title "$title" \
            --body-file "$REPORT_FILE"

.github/prompts/sleeping.md

# Sleeping Mode

You are running in Sleeping mode for this repository.

Goal:
Verify that repo-owned durable memory is consistent with the actual repository and any runtime evidence available in CI.

Rules:

- Do not commit changes.
- Do not push changes.
- Do not open pull requests.
- Do not modify product code, schema, deploy, billing, auth, or infrastructure.
- Read `AGENTS.md` and `docs/agent/*` first.
- Inspect package scripts, deploy scripts, config files, scheduled jobs, linked repos, and recent git history.
- Check whether required durable memory files exist:
  - `AGENTS.md`
  - `docs/agent/STATE.md`
  - `docs/agent/RUNBOOK.md`
  - `docs/agent/DECISIONS.md`
  - `docs/agent/LINKED_REPOS.md`
- Report only findings that are actionable or useful for recovery.
- If something is missing or stale, explain the evidence and propose the smallest safe fix.
- For every finding, include affected file paths in backticks, for example `src/example.ts`, so the workflow can identify recent commit authors and mention them in the issue.

Output Markdown with these sections:

## Summary

One paragraph.

## Findings

Use bullets. Include affected file paths in backticks and explain the evidence.

## Suggested Work Items

Use bullets. Include completion evidence for each suggested item.

## Skipped Checks

List anything you could not verify from CI and why.

The important property is the contract: Claude Code audits reality, writes a report, and opens an issue for relevant drift without committing to the branch.