Project-Pulse Skill

A sibling skill to phase-tracking — project-scoped, structured, and built for a monitoring dashboard. Where phase-tracking manages in-session state, project-pulse broadcasts it outward and records the full project lifecycle.

Load both skills side by side: phase-tracking writes the state, project-pulse adds timestamps, identity, events, and export surfaces. They share project_state.json and own different concerns.

When to use

Use project-pulse alongside phase-tracking when:

• You want to track progress across multiple projects from a single dashboard
• You need phase velocity metrics (how long does each phase take?)
• You want alerts on stalled phases or aging issues
• You need a structured event log for compliance or post-mortems
• You're building a monitoring or reporting layer on top of phased delivery

Do not use project-pulse alone — it reads project_state.json written by phase-tracking. Always load phase-tracking first.

Relationship with phase-tracking

| Concern | Owned by | |---|---|---| | State mutations (phase transitions, ADRs, issues) | phase-tracking | | Schema v1.1 structured fields (timestamps, events, project_id) | Both | | Schema validation | project-pulse | | Event log (append-only chronological record) | project-pulse |

Schema: project_state.json v1.1

The v1.1 schema extends phase-tracking's v1.0 with timestamps, structured objects, project identity, and an event log. Existing v1.0 files continue to work — missing v1.1 fields produce warnings but no errors.

Full schema

{
  "schema_version": "1.1",
  "project_id": "my-project-slug",
  "project_name": "My Project",

  "current_phase": "Phase 3 — Auth & Permissions",
  "current_phase_started_at": "2026-06-10T08:00:00Z",

  "completed_phases": [
    {
      "name": "Phase 1 — Project scaffold & config",
      "started_at": "2026-06-01T09:00:00Z",
      "completed_at": "2026-06-03T17:30:00Z",
      "duration_hours": 32.5
    }
  ],

  "pending_phases": ["Phase 4 — API routes"],

  "architecture_decisions": [
    {
      "id": "ADR-001",
      "title": "Use row-level security with Postgres RLS",
      "status": "Accepted",
      "recorded_at": "2026-06-05T14:00:00Z"
    }
  ],

  "known_issues": [
    {
      "id": "ISS-001",
      "description": "Refresh token rotation not implemented",
      "severity": "medium",
      "status": "open",
      "opened_at": "2026-06-08T10:00:00Z"
    }
  ],

  "event_log": [
    { "type": "phase_started",     "phase": "Phase 1", "timestamp": "2026-06-01T09:00:00Z" },
    { "type": "phase_completed",   "phase": "Phase 1", "timestamp": "2026-06-03T17:30:00Z" },
    { "type": "adr_recorded",      "adr": "ADR-001",   "timestamp": "2026-06-05T14:00:00Z" }
  ],

  "next_steps": "Implement JWT verify middleware",
  "updated_at": "2026-06-13T10:00:00Z"
}

Field reference

Migration from v1.0

When loading an existing v1.0 project_state.json, the agent:

1. Detects missing v1.1 fields
2. Logs a warning listing which fields are absent
3. Prompts the user: "This project uses the v1.0 schema. Add v1.1 fields (project_id, timestamps, event_log) for monitoring support? [y/N]"
4. If yes, writes default values (project_id from repo name, event_log: [], etc.)
5. Proceeds in either case — no hard error

Completed phases — object format

Each completed phase object:

If started_at is missing, duration_hours is omitted.

Architecture decisions — object format

Each ADR object:

Known issues — object format

Each issue object:

Event log

The event_log is a chronological array of project lifecycle events. It is the source of truth for monitoring — every transition generates one event.

Event types

Event format

{
  "type": "phase_completed",
  "phase": "Phase 2 — Database schema & migrations",
  "timestamp": "2026-06-08T17:30:00Z",
  "duration_hours": 32.5
}

Ordering guarantees

• Events are appended in chronological order (newest at end)
• Timestamps should be monotonic — a new event MUST NOT have a timestamp older than the last event
• If the agent's clock cannot be trusted, use updated_at as the event timestamp

Workflow

1. Initialize

Run this once when setting up a new project. Typically done by phase-tracking's Initialize step with project-pulse adding monitoring fields.

1. Ask the user for the complete list of phases.
2. Ask for project_id (default: repo directory name) and project_name.
3. Write project_state.json:
   • Set schema_version: "1.1"
   • Set project_id and project_name
   • Set current_phase to Phase 1, current_phase_started_at to now
   • completed_phases: []
   • All phases in pending_phases
   • event_log: []
4. Append a project_created event to event_log.
5. Create the first todo breakdown for Phase 1 using todowrite.

After every project_state.json write, run the validation gate (see Health checks & validation section).

If project_state.json is missing: treat as fresh start (same as phase-tracking). Prompt for project_id and project_name before creating the file.

2. Start a phase

When beginning work on a phase:

1. Read project_state.json to confirm current phase.
2. Set current_phase_started_at to the current timestamp (ISO 8601).
3. Break the phase into atomic tasks using todowrite.
4. Append a phase_started event to event_log.
5. Mark the first todo in_progress and proceed.

3. Complete a phase

When all todos for the current phase are marked completed:

1. Calculate duration_hours from current_phase_started_at to now.
2. Move the phase to completed_phases as an object:

   {
     "name": "Phase N — Title",
     "started_at": "<current_phase_started_at>",
     "completed_at": "<now>",
     "duration_hours": <calculated>
   }

3. Set current_phase to the next phase in pending_phases (shift from front).
4. Set current_phase_started_at to the current timestamp for the new phase.
5. Append a phase_completed event to event_log.
6. If no phases remain, set current_phase to "Complete" and current_phase_started_at to null.
7. Update next_steps with the next phase goal.
8. Run full project verification (all tests, lint, typecheck).

4. Record an ADR

When an important architectural decision is made:

1. Write the full ADR as a dedicated file at docs/adr/NNN-title-of-decision.md with context, decision, consequences, and status.
2. Append an object to architecture_decisions:

   {
     "id": "ADR-NNN",
     "title": "Title of decision",
     "status": "Accepted",
     "recorded_at": "<now>"
   }

3. Append an adr_recorded event to event_log.
4. Increment the ADR number (maintain monotonic ordering).

If no docs/adr/ directory exists, store the full ADR inline under architecture_decisions as an object with a details field. Prefer dedicated files once the project has more than 5 ADRs.

5. Manage known issues

When a problem is identified:

1. Assign the next ISS-NNN ID.
2. Append an object to known_issues with all required fields.
3. Append an issue_opened event to event_log.

When an issue is resolved:

1. Set status to "resolved" and resolved_at to now.
2. Append an issue_resolved event to event_log.

6. Session handoff

When ending a session mid-phase:

1. Ensure all v1.1 fields are set (timestamps, event_log entries appended).
2. Update updated_at to the current timestamp.
3. Update next_steps to precisely describe what comes next.

When resuming after a session gap:

1. Read project_state.json first. Check schema_version to decide which fields to expect.
2. If v1.0, offer to upgrade to v1.1 (see Migration from v1.0).
3. Create fresh todos from next_steps + current_phase.

Webhook delivery (external)

The agent's only webhook responsibility is appending events to event_log. Delivery to external systems (Slack, Datadog, custom dashboards) is handled by a sidecar process — cron, inotify, or CI — that reads project_state.json, detects new events, and POSTs them with HMAC-SHA256 signing.

This keeps HTTP IO, retries, and error handling out of the agent's critical path.

See project-pulse-webhook-sidecar.md for the full sidecar pattern, including delivery scripts, retry policies, and cursor-based event tracking.

Export & snapshot (external)

Exporting project_state.json to a collector, archive, or CI pipeline is also handled outside the agent. Patterns include cron-based push, GitHub Actions steps, and timestamped archive snapshots — all documented in the sidecar idea.

See project-pulse-webhook-sidecar.md for export and delivery patterns.

Health checks & validation

Run these commands to verify project_state.json integrity.

v1.1 validation gate

Run after every project_state.json write:

python3 -c "
import json, sys
d = json.load(open('project_state.json'))
assert d.get('schema_version'), 'schema_version is required'
assert d.get('project_id'), 'project_id is required'
assert d.get('project_name'), 'project_name is required'
assert isinstance(d.get('event_log'), list), 'event_log must be a list'
assert isinstance(d.get('completed_phases'), list), 'completed_phases must be a list'
assert isinstance(d.get('pending_phases'), list), 'pending_phases must be a list'
print('project-pulse: state is valid (v1.1)')
"

Assertions that must hold

• schema_version is present and non-empty
• project_id is a non-empty string
• completed_phases and pending_phases have no overlapping phase names
• completed_phases is in chronological order by completed_at
• pending_phases is in chronological order
• ADR numbers are monotonic and sequential
• current_phase is never in both completed_phases and pending_phases
• Event log entries have type, timestamp and type-specific required fields
• No events reference phases not present in completed_phases or pending_phases
• Timestamps are valid ISO 8601 strings

Integration with subagents

When delegating work for a project-pulse-monitored phase to a subagent, include this context in the prompt:

CONTEXT: project-pulse monitoring active for [project_id].
State schema version: [1.0|1.1].
Current phase: [current_phase].
All state transitions MUST be recorded in event_log with ISO 8601 timestamps.

This keeps subagents aligned with the monitoring requirements even though they don't have access to the full session history.

Loading order

When using both skills, load phase-tracking first (it creates project_state.json), then project-pulse second (it manages monitoring fields).

// Correct loading order
// 1. phase-tracking — manages state mutations
// 2. project-pulse — manages monitoring and events

No locking is needed — agents operate sequentially within a single session. The two skills write to different sets of fields in the same JSON file.

Further reading

The full design exploration for monitoring dashboards, metrics, and visualization tools is documented alongside the sidecar delivery pattern:

• Dashboard & metrics design: phase-tracking-monitoring-integration.md
• Sidecar webhook delivery: project-pulse-webhook-sidecar.md