Project State Skill | Agent Skills

last_updated: 2026-03-02T14:30:00Z session_count: 12 current_milestone: v1.0

Project State

Current Work

Phase: 72
Task: Implement OAuth2 login flow
Status: executing
Plan: PLAN-1.md (task 3 of 5)

Completed Phases

[x] Phase 70: Project setup and scaffolding
[x] Phase 71: Database schema and migrations

Blockers

[ ] [HIGH] API key for OAuth provider not configured (@user, 2026-03-01)

Decisions

| Date | Decision | Rationale | |------|----------|-----------| | 2026-02-28 | Use PostgreSQL over SQLite | Need concurrent writes for API | | 2026-03-01 | Skip Phase 71.1 (Redis cache) | Not needed for v1.0 |

Quick Tasks

| # | Task | Status | Date | |---|------|--------|------| | 001 | Fix login redirect | done | 2026-02-28 | | 002 | Add rate limiting | in-progress | 2026-03-02 |


### 2. Update Individual Fields

Update a single field without affecting the rest of the document:

update current_phase -> 73 update current_task -> "Build API endpoints for user management" update status -> "planning"


Use `Edit` tool to perform surgical updates on specific lines.

### 3. Append to List Fields

Add items to list-type fields:

append completed_phases -> "Phase 72: OAuth2 authentication" append decisions -> { date: "2026-03-02", decision: "Use JWT tokens", rationale: "Stateless auth for API" } append blockers -> { severity: "MEDIUM", description: "Need design mockups", owner: "@designer" }


### 4. Remove from List Fields

Remove items when resolved:

remove blocker -> "API key for OAuth provider not configured"


Mark blockers as resolved rather than deleting (change `[ ]` to `[x]`).

### 5. Quick Tasks Table Management

Add, update, and query quick tasks:

add_quick_task -> { number: 3, task: "Update README", status: "pending" } update_quick_task -> { number: 2, status: "done" } query_quick_tasks -> { status: "in-progress" }


### 6. Cross-Session Memory

STATE.md persists across context resets. On session start:
1. Read STATE.md to restore project context
2. Increment `session_count` in frontmatter
3. Update `last_updated` timestamp
4. Report state summary to orchestrator

### 7. Decision Log

Structured decision tracking with timestamps and rationale:

```markdown
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-03-02 | Use JWT tokens | Stateless auth for API |

8. Blocker Tracking

Track blockers with severity and ownership:

- [ ] [HIGH] API key not configured (@user, 2026-03-01)
- [x] [MEDIUM] Design mockups needed (@designer, 2026-02-28) - resolved 2026-03-01

Severity levels: HIGH (blocks current work), MEDIUM (blocks future work), LOW (inconvenience).

Tool Use Instructions

Reading State

Use Read to load .planning/STATE.md
Parse frontmatter for metadata (last_updated, session_count, current_milestone)
Parse markdown sections into structured fields
Return parsed state object

Updating a Field

Use Read to load current STATE.md
Locate the target field/section
Use Edit with precise old_string/new_string to update only the target
Verify edit succeeded by reading the section back

Appending to Lists

Use Read to find the end of the target list section
Use Edit to insert new item at the correct position
For tables, append new row before the section break

Resolving Blockers

Use Read to find the blocker text
Use Edit to change - [ ] to - [x] and append resolution date

Process Integration

This skill is used by most GSD processes:

execute-phase.js - Update current_task as each task completes, track position
verify-work.js - Add/resolve blockers based on verification results
audit-milestone.js - Read completed_phases for coverage analysis
progress.js - Read full state for progress display and routing
quick.js - Add/update quick tasks table
debug.js - Track debug sessions, add blockers for unresolved issues
complete-milestone.js - Clear completed_phases, reset current_task
add-tests.js - Update state with test coverage info

Output Format

{
  "operation": "read|update|append|remove",
  "field": "current_phase|completed_phases|blockers|decisions|quick_tasks",
  "status": "success|error",
  "previousValue": "...",
  "newValue": "...",
  "stateSnapshot": {
    "currentPhase": 72,
    "currentTask": "Implement OAuth2",
    "completedPhases": [70, 71],
    "activeBlockers": 1,
    "quickTasksTotal": 3,
    "quickTasksPending": 1
  }
}

Configuration

| Setting | Default | Description | |---------|---------|-------------| | stateFile | .planning/STATE.md | Path to STATE.md | | autoTimestamp | true | Auto-update last_updated on write | | autoSessionCount | true | Auto-increment session_count on read | | blockerSeverityLevels | HIGH,MEDIUM,LOW | Valid blocker severities |

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | STATE.md not found | Planning directory not initialized | Run gsd-tools init first | | Section not found | Unexpected STATE.md format | Rebuild STATE.md from template | | Edit collision | Non-unique text match for edit | Provide more context in old_string | | Frontmatter parse error | Malformed YAML frontmatter | Fix YAML syntax or regenerate | | Concurrent modification | Multiple processes editing state | STATE.md is not lock-protected; serialize access |

Constraints

STATE.md must remain human-readable markdown at all times
Never delete historical entries (blockers, decisions); mark as resolved instead
Frontmatter must be valid YAML
Quick task numbers must be sequential
All timestamps must be ISO 8601 format
Decision log must be append-only (no editing past decisions)
Blocker resolution must preserve the original blocker text

Agent Skills: Project State

Install this agent skill to your local

Skill Files