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:
5. swarm → pulse:swarming allowed
6. single-worker → skip swarming, use pulse:executing
7. planning-only → do not start execution
8. 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.

| # | Skill | Load when... | |---|---|---| | 0 | pulse:preflight | Starting, resuming, or before execution-capable flow | | 1 | pulse:using-pulse | After preflight on any Pulse session | | 1b | pulse:brainstorming | Intent is vague and design is not locked | | 2 | pulse:exploring | Feature intent exists but implementation decisions are fuzzy | | 3 | pulse:planning | Decisions are locked and implementation planning is next | | 4 | pulse:validating | Current work and beads must be proven execution-ready | | 5 | pulse:swarming | recommended_mode=swarm and execution is approved | | 6 | pulse:executing | Direct implementation is happening | | 7 | pulse:reviewing | Execution is complete and quality gate is next | | 8 | pulse:compounding | Completed Pulse cycle and post-cycle machine learnings should be captured | | 9 | pulse:systematic-debug-fix | Agent path is blocked by failures | | 10 | pulse:gitnexus | Architecture/discovery/impact questions when configured | | 11 | pulse:dev-note | User explicitly asks to record one learning from this conversation | | 12 | pulse:dev-note-distil | User asks to distill accumulated dev-notes into reader-facing topics | | 13 | pulse:dream | User asks to consolidate runtime artifacts into machine-readable memory | | 14 | pulse:writing-pulse-skills | Editing Pulse skills | | 15 | pulse:architecture-rescue | Architecture cleanup report is requested | | 16 | pulse:bootstrap-project-context | Project-doc bootstrap or glossary setup is requested |

Routing Logic

Mode Selection

| Mode | Use when... | |---|---| | small_change | Low-risk local fix/tweak with no new capability/API/data-model/ownership boundary | | standard_feature | Default for feature work and medium-scope refactors | | high_risk_feature | Cross-cutting or high-blast-radius feature/refactor work |

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

| Request type | First skill | |---|---| | Unformed idea / unclear design intent | pulse:brainstorming | | Feature intent is clear but implementation decisions are unresolved | pulse:exploring | | Clear implementation request with decisions already locked (approved CONTEXT.md) | pulse:planning | | Small low-risk fix | pulse:exploring for an approved mini CONTEXT.md, then pulse:planning (small_change) | | "Review my code" | pulse:reviewing | | "Note this learning from this conversation" | pulse:dev-note | | "Distill accumulated dev notes for reading" | pulse:dev-note-distil | | "Consolidate runtime artifacts into machine memory" | pulse:dream | | "Capture post-cycle machine learnings" | pulse:compounding | | "Improve Pulse itself" | pulse:writing-pulse-skills | | "Architecture rescue" asks | pulse:architecture-rescue | | Architecture/discovery asks | pulse:gitnexus