Using Pulse

using-pulse

Bootstrap meta-skill. Load this after pulse:preflight to route into the correct next Pulse skill and resume safely inside a preflight-ready Pulse environment.

Use this 3-plane model:

• Operator plane — user goal, approvals, active mode, and next gate.
• Cookbook plane — which Pulse skill to invoke next.
• Scout plane — repo truth: onboarding/tooling health, state mirrors, handoffs, checkpoints, and memory pointers.

This skill is a pure router + scout brief inside a preflight-ready Pulse runtime. It does not replace downstream skill contracts, and it does not make onboarding/remediation or runtime-readiness decisions.

Preflight Contract

pulse:preflight is the sole readiness authority for a Pulse session.

• If preflight readiness is missing or stale in .pulse/tooling-status.json, invoke pulse:preflight.
• If .pulse/tooling-status.json is missing, invoke pulse:preflight.
• If preflight reported FAIL or blocked, stop and present that result instead of re-checking tooling here.
• Missing br/bv is a preflight blocker for Pulse execution-capable routing; this skill must not treat missing bead tooling as a local workaround case.
• If preflight reported DEGRADED, route within the approved downgrade and do not rerun onboarding or tool-health checks.
• If dependency warnings are surfaced in preflight output, keep command-vs-MCP wording explicit:
  • Missing commands: ...
  • Missing MCP server configuration: ...

Do not run onboard_pulse.mjs --apply from this skill. Any onboarding or remediation change belongs to pulse:preflight.

Before Anything Else

1. Read .pulse/tooling-status.json.
2. If .pulse/scripts/pulse_status.mjs exists, run node .pulse/scripts/pulse_status.mjs --json.
3. If the scout script is missing, or preflight readiness artifacts are missing/stale/blocked, run pulse:preflight first.
4. Respect recommended_mode from preflight:
   • swarm → pulse:swarming allowed
   • single-worker → skip swarming, use pulse:executing
   • planning-only → do not start execution
   • blocked → clear blockers first

Session Scout

After onboarding, run:

node .pulse/scripts/pulse_status.mjs --json

Scout is read-only orientation. It summarizes onboarding, dependency health, state mirrors, handoffs, advisory checkpoints, project-doc routing hints, and targeted memory recall.

Scout output is context, not a gate bypass. Keep gates and downstream skill contracts intact.

Project docs are part of the scout contract:

• if .pulse/project-docs.json is mapped, read the mapped repo-level docs before feature history when terminology or architecture boundaries matter
• if project docs are only detected, surface that and consider pulse:bootstrap-project-context before deeper planning
• if project docs are missing, do not invent a repo glossary silently; keep the absence explicit

Checkpoint and State Posture

Checkpoint files under .pulse/checkpoints/<feature>/... are advisory snapshots only.

Authoritative sources remain:

1. active entries in .pulse/handoffs/manifest.json
2. owner handoff file selected from the active manifest
3. current state mirrors (.pulse/state.json, .pulse/STATE.md)

Use checkpoints for quick comparison, recall hooks, and resume briefing acceleration. Never treat checkpoints as a second state machine.

See references/handoff-contract.md for canonical pause/resume companion rendering, and references/history-lifecycle-contract.md for durable audit expectations.

GitNexus Readiness Is Part of Session Start

Treat gitnexus as preferred discovery when configured.

• configured = true: prefer pulse:gitnexus, then verify with file reads.
• configured = false: continue with grep/file inspection.
• Use matched_sources to verify where MCP config came from.

Readiness here is config availability, not index-quality validation.

Dependency Declaration Contract

Every packaged Pulse skill must make its dependency posture explicit. There are only three valid states:

1. Command-backed skill — declare each required CLI under metadata.dependencies with kind: command, the binary name in command, a truthful missing_effect, and a short reason.
2. MCP-backed skill — declare each required MCP server under metadata.dependencies with kind: mcp_server, the expected server_names, the supported config_sources, a truthful missing_effect, and a short reason.
3. Dependency-free packaged skill — declare metadata.dependencies: [] to say the skill was reviewed and does not rely on first-class external tools.

Do not leave a packaged skill with undeclared dependency posture.

When updating or adding packaged Pulse skills, run:

• node skills/using-pulse/scripts/test_onboard_pulse.mjs
• bash scripts/sync-skills.sh --dry-run

Routing Cookbook

Use this routing cookbook to route into the next specialist skill. It is a maintained using-pulse routing aid, not a complete packaged-skill inventory.

Routing Logic

Mode Selection

If a request introduces user-visible capability, workflow, subsystem, API surface, durable data-model change, or ownership boundary, it is feature work.

First-Skill Routing

Deterministic tie-breaker:

• If the request is still unclear after a quick scout (problem, user, or success criteria not concrete), route to pulse:brainstorming first.
• Otherwise, route to pulse:exploring.

Maintenance rule: when adding/removing a first-skill routing row in the table above, update this Routing Cookbook in the same change.

Do not route directly to pulse:planning unless an approved history/<feature>/CONTEXT.md already exists for this exact work slice.

Gate and State Ownership

Entry-layer ownership is explicit:

• pulse:preflight owns readiness artifacts (.pulse/tooling-status.json, .pulse/state.json, preflight status in .pulse/STATE.md).
• pulse:using-pulse owns routing guidance only; it must not rewrite gate outcomes from later phases.
• pulse:exploring owns writing history/<feature>/CONTEXT.md and handoff-ready state hints.
• Gate 1 approval is a human decision on history/<feature>/CONTEXT.md; after approval, runtime state should carry gate_status: approved, next_skill_recommended: pulse:planning, and next_action: manual_invoke by default.

Do not mark Gate 1 approved before explicit user approval.

Resume Logic

Resume handling stays in the scout plane.

1. Read .pulse/handoffs/manifest.json.
2. Present active handoffs by owner, skill, feature, active work slice, summary, and next action.
3. If multiple active entries exist, ask user which one to resume.
4. Open only the selected owner file and resume from summary, next_action, read_first, and payload.transfer.
5. Optionally use latest matching checkpoint as advisory aid.
6. Load the chosen handoff skill and continue.
7. Do not auto-resume without user confirmation.

Canonical pause/resume schema and rendered companion contract live in references/handoff-contract.md.

Go Mode

Go mode is the full operator-plane pipeline with 4 human gates. Canonical details live in references/go-mode-pipeline.md.

Trigger:

• /go <feature>
• "run the full pipeline"
• "go mode"

Non-negotiable gates:

• Gate 1: approve history/<feature>/CONTEXT.md
• Gate 2: approve selected shape artifact (work-shape.md, phase-plan.md, or epic-map.md)
• Gate 3: approve feasibility-validated current work execution
• Gate 4: approve merge after reviewing (P1 findings still block)

Execution branch from preflight:

• recommended_mode=swarm → pulse:swarming
• recommended_mode=single-worker → pulse:executing
• recommended_mode=planning-only|blocked → do not start execution

Priority Rules

1. P1 review findings always block merge.
2. Context budget always applies: if context exceeds 65%, current owner writes its own handoff and updates manifest.
3. CONTEXT.md is source of truth for product and architecture decisions.
4. Planning owns critical-patterns.md ingestion; workers execute from bead context first.
5. Planning defines spike_question for each HIGH-risk item; validating owns spike bead creation/execution.
6. GATE 3 is critical. If plan soundness is uncertain, do not approve execution.
7. Spike failures halt pipeline and route back to planning.
8. Preflight decides swarming vs direct executing path.
9. Never skip validating.

Red Flags

Pause and surface immediately when:

• flow jumps from exploring to execution
• execution starts with recommended_mode=blocked
• retired/global handoff path is used instead of owner-scoped handoffs
• HIGH-risk plan has no spike_question
• review is skipped outside approved lightweight small_change flow
• active handoff manifest/file references are inconsistent
• state.json or STATE.md is stale after active-work transition

File Quick Reference

.pulse/tooling-status.json            <- preflight output
.pulse/state.json                     <- machine-readable routing/status mirror
.pulse/STATE.md                       <- shared project state
.pulse/project-docs.json              <- project-doc routing map
.pulse/handoffs/manifest.json         <- active handoff index (authoritative)
.pulse/checkpoints/<feature>/...      <- advisory checkpoint snapshots
history/<feature>/CONTEXT.md          <- locked decisions from exploring
history/<feature>/work-shape.md       <- approved shape for direct/spike/small work
history/<feature>/phase-plan.md       <- approved shape for milestone/phase-shaped work
history/<feature>/epic-map.md         <- approved shape for capability/risk-shaped work
history/<feature>/lifecycle-summary.md <- durable audit summary

References

• references/go-mode-pipeline.md
• references/handoff-contract.md
• references/history-lifecycle-contract.md