session-start

name	session-start
description	Start new session with full context and greeting
disable-model-invocation	false
wrought	{"version":"1.0","tools":{"capabilities":["read_file","search_content","find_files","run_command"]},"platforms":{"claude-code":{"allowed-tools":"Read, Grep, Glob, Bash","disable-model-invocation":false}},"agent":{"role":"Session Manager","expertise":["context loading","session initialization"],"non_goals":["implementation","investigation"]},"execution":{"default_mode":"react","stop_conditions":["Session greeting displayed","User instructed to stop"]},"output":{"format":"markdown","template":"session greeting (displayed, not saved)","required_sections":["Greeting","Last session summary","Priorities"]},"pipeline":{"track":"standalone","standalone":true,"prerequisites":[],"produces":["session context (in-memory)"]}}

Session Start Protocol

Step 1: Get Current Time

date -u '+%A, %B %d, %Y at %H:%M UTC'

Step 2: Read Session Config

Look for configuration in CLAUDE.md between markers:

• <!-- SESSION_CONFIG_START --> and <!-- SESSION_CONFIG_END -->

Extract:

• user_name: Who to greet
• project_name: Project name
• timezone: User's timezone for display
• session_docs: Additional docs to read

If no config exists, use defaults and infer from context.

Step 3: Read Handoff Document

Find the imported handoff in CLAUDE.md between:

<!-- SESSION_HANDOFF_START -->
@NEXT_SESSION_PROMPT_xxxx.md
<!-- SESSION_HANDOFF_END -->

Read that file for full session context.

Step 3.5: First-Session Setup

After reading the handoff (or determining this is the first session), check for first-session indicators. Each check is independent — if one fails or is declined, continue to the next.

Environment Profiling

IF .wrought exists AND no file matching docs/analysis/*_environment_profile.md:

1. Announce: "This is a new Wrought™ project. Let me profile your environment."
2. Auto-invoke /safeguard detect (full interactive flow with checkpoints)
3. After completion, continue to next check

Architecture Discovery

IF no docs/analysis/system-map.md exists:

1. Announce: "Building initial architecture inventory..."
2. Auto-invoke /analyze discover
3. After completion, continue to next check

GitHub Projects Integration

Read .wrought marker and check github_owner and github_project_number fields.

IF github_owner is set (not "none") AND github_project_number is "none" or missing:

Do NOT offer to create a board until every recovery check below has been tried. A github_project_number of "none" on a project that clearly had a board is the signature of the marker-reset defect fixed in 1.2.1 — creating a second board consumes a project number and orphans the real one. Check in order:

1. Sync-protocol doc — if docs/reference/github_projects_sync_protocol.md exists and records a Project Number + ID, do not offer to create. Say: "The marker says github_project_number=none, but the sync protocol records board #{N} ({ID}). That is the signature of the marker-reset defect, not a missing board." Restore both marker fields by read-modify-write (preserving every other field), leave the doc untouched, and continue.
2. Git history — if git log --format=%H -- .wrought is non-empty and the newest revision carries a non-"none" github_project_number, restore both fields from it by read-modify-write and continue.
3. Existing board — if gh is available and authenticated, list the owner's projects. If "{project_name} Wrought Evolution" already exists, offer to adopt it (record its number + ID in the marker). Never offer to create a second board with the same name.
4. Only if 1–3 find nothing: ask "GitHub detected ({github_owner}/{github_repo}). Create a Wrought-integrated Projects board? [Y/n]"
   • If yes: proceed to Step 3.6 (GitHub Projects Provisioning)
   • If no: skip, note in greeting that GitHub Projects can be set up later

---

Step 3.6: GitHub Projects Provisioning

This step creates a GitHub Projects board with Wrought-aligned custom fields. Only execute if requested in Step 3.5.

1. Check Token Scope

gh auth status

• If missing project scope: suggest gh auth refresh -s project
• If auth fails: warn and skip (non-fatal)

2. Create Project

PROJECT_NUMBER=$(gh project create --owner {github_owner} \
  --title "{project_name} Wrought Evolution" \
  --format json --jq '.number')

3. Create Custom Fields (8 fields)

Create each field using gh project field-create:

Field	Type	Options
Pipeline	Single Select	Reactive, Proactive, Audit, Self-Evolution, BAU
Lifecycle Stage	Single Select	Open, Investigating, Designing, RCA Complete, Blueprint Ready, Planned, Implementing, Resolved, Verified
Type	Single Select	Defect, Vulnerability, Gap, Debt, Drift
Severity	Single Select	Critical, High, Medium, Low
Finding ID	Text	—
Evidence	Text	—
Workstream	Single Select	BAU, Roadmap, TechDebt
Area	Single Select	CLI, Skills, Tracker, Lifecycle, Hooks, Docs, SDLC/Release

4. Capture Field IDs

gh project field-list {PROJECT_NUMBER} --owner {github_owner} --format json

5. Get Project Node ID

PROJECT_ID=$(gh project view {PROJECT_NUMBER} --owner {github_owner} --format json --jq '.id')

6. Generate Sync Protocol

Hard no-clobber. If docs/reference/github_projects_sync_protocol.md already exists, NEVER overwrite it — it is typically the only on-disk record of that project's Lifecycle Stage option IDs, and regenerating it from a newly created (empty) board destroys them. Instead write docs/reference/github_projects_sync_protocol.NEW.md beside it, stop, and ask the human to diff the two and merge deliberately.

Only when no such file exists: generate docs/reference/github_projects_sync_protocol.md from the captured IDs, using the same format as the existing Wrought sync protocol file if one is available as a reference.

7. Update Marker

Update .wrought marker with:

• github_project_number={PROJECT_NUMBER}
• github_project_id={PROJECT_ID}

This is a read-modify-write: read the existing .wrought, change only the two fields above, and write every other field back unchanged — including any key outside the documented schema. Never rebuild the marker from defaults. (This is the rule /safeguard Step 7 already states; the CLI defect fixed in 1.2.1 was the same mistake in Python.)

8. Report

Print: "GitHub Projects board created: {project_name} Wrought Evolution (#{PROJECT_NUMBER})"

All steps in 3.6 are non-fatal — if any step fails, warn and continue.

---

Step 3.7: Intelligence Inbox Review

Check docs/intelligence/inbox.md for items collected since last session.

1. Use Read to open docs/intelligence/inbox.md
2. If empty (no items below the --- header), skip silently
3. If items exist, present them grouped by date:

   **Intelligence Inbox** ({N} new items):
   - {tag} {one-line summary} — {link}
   

4. For each item, ask the user to triage:
   • Actionable → "This needs a /finding — shall I create one?"
   • Reference → Move the item to docs/intelligence/archive.md (append under a date heading, preserve tags and notes)
   • Ignore → Delete the item from inbox
   • Skip for now → Leave in inbox for next session
5. After triage, Edit inbox.md to remove processed items (keep the header template)
6. Continue to next step

This step is non-fatal — if docs/intelligence/inbox.md does not exist, skip silently.

---

Step 3.8: Workflow Awareness

Check for active Findings Trackers to surface "you are here" context:

1. Use Glob to find docs/findings/*_FINDINGS_TRACKER.md
2. If trackers exist, Read each and identify findings NOT Resolved or Verified
3. For each active finding, note: number, title, current stage, suggested next skill
4. Include in the Current Status section of the greeting:

   **Active Workflows**:
   - F1: {title} — Stage: {stage} — Next: /{next_skill}
   

5. If wrought CLI available, suggest: "Run wrought workflow status for full details"

This step is non-fatal — if docs/findings/ does not exist, skip silently.

---

Step 3.9: Active Constraints Review

Surface in-force cross-session constraints so decisions don't evaporate post-compaction:

1. Use Read to open CLAUDE.md and locate the ## Active Constraints (in force) section
2. If the section is absent, skip silently (plugin-only installs / not-yet-seeded projects) — do NOT emit any greeting line
3. If present, read the ### Durable invariants and ### Time-bounded / ephemeral subsections directly — do NOT depend on the wrought CLI being installed
4. For each EXPIRES <YYYY-MM-DD> entry, compare the date to today; flag any with a past date as LAPSED (prune or re-stamp). CLEARS-WHEN and SUPERSEDED-ONLY entries are always active (manual review)
5. Include in the Current Status section of the greeting (omit entirely if there are no constraints):

   **Active Constraints**:
   - [CST-001] {one-line text} — clears: {predicate}
   - [CST-003] {one-line text} — LAPSED (expired {date}) — prune or re-stamp
   

6. If the wrought CLI is available, you may optionally suggest: "Run wrought constraints check for active/lapsed counts" (date computation only — never required)

This step is non-fatal — if CLAUDE.md has no ## Active Constraints (in force) section, skip silently.

---

Step 4: Provide Greeting

Format your response as:

Good [morning/afternoon/evening] {user_name}!

It's {current_datetime} UTC ({local_time} {timezone}).

I've read the session handoff and I'm oriented with the {project_name} project.

**Last Session**: {brief summary from handoff}

**Current Status**:
- {status item 1}
- {status item 2}

**Priorities**:
1. {priority 1}
2. {priority 2}
3. {priority 3}

What would you like to work on today?

Model tip (routing floor + opusplan): the Pass-A routing floor recommends Opus as the quality default for every pipeline stage — launch with /model opus, or query wrought route <stage>. opusplan remains a cost-conscious alternative; read its coverage honestly: it covers only the /plan checkpoint gate (Opus reasons in plan mode, then execution runs on Sonnet) — it does not apply to /design, /blueprint, /investigate, /research, or any other pipeline stage, all of which run outside plan mode and would silently run below the floor. To get Opus-level reasoning on those stages, use /model opus manually or delegate the sub-step to an Agent-tool spawn with an explicit model override. This is a policy with partial automation — residual manual /model control remains at the main loop.

Step 5: Confirm Context

After greeting, confirm you have loaded:

• CLAUDE.md (auto-loaded)
• Session handoff document
• Any additional session_docs from config

---

Time of Day Guidelines

Based on UTC time, determine greeting:

• 05:00-11:59 UTC: "Good morning"
• 12:00-16:59 UTC: "Good afternoon"
• 17:00-04:59 UTC: "Good evening"

Adjust if user's timezone is specified in config.

---

Check for Active Plan Files

1. Check docs/plans/ for recent plan files
2. If active plan exists, read it and note:
   • Current phase/status
   • What phases are complete
   • What's next
3. Include plan status in the summary if applicable

---

If No Handoff Exists

If this is the first session (no handoff file):

Hello {user_name}!

It's {current_datetime}.

This appears to be the first session for this project. I've read CLAUDE.md and I'm ready to help.

**Project**: {project_name}

Would you like me to help you set up the session management system, or shall we dive into the work?