agentleFS
sponge-b0bsponge-b0b/Polaris/.agents/skills/project-delivery-management/SKILL.md

project-delivery-management

Skill4 starsChanged 4 months agoApache-2.0View on GitHub

Coordinate project-level delivery across current Polaris Wayfinder efforts by owning durable focus, exact parallel-focus authorization, cross-Wayfinder dependency placement, and fail-closed delivery guards.

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 17 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Never copy, cherry-pick, merge, or synchronize scripts/project_delivery.py or its tests into a verified/reviewed Spec branch merely to …

    line 53
  2. Distinctive:

    If a clean exact default-branch execution plane cannot be proven, fail closed.

    line 59
  3. Distinctive:

    Do not use GitHub search syntax, body/title matching, Project fields, remembered issue numbers, or a previously observed singleton as a …

    line 91
  4. Distinctive:

    Do not persist frontier, queue order, blocked state, priority, lifecycle stage, Project fields, or dependency registries in the singleton.

    line 115
  5. Distinctive:

    Only an explicit human invocation may make a discretionary focus choice:

    line 122
  6. Distinctive:

    Every focus-changing operation names exact Wayfinder issue numbers or URLs.

    line 132
  7. Distinctive:

    Never derive frontier membership from Project fields, priority, issue order, assignees, branch state, recency, or activity.

    line 178
  8. Distinctive:

    every focused issue is a current canonical Wayfinder map.

    line 185
  9. Distinctive:

    every focused map is frontier-eligible.

    line 186
  10. Distinctive:

    Before changing current focus, append:

    line 194
  11. Distinctive:

    If that comment cannot be persisted, do not mutate the singleton.

    line 204
  12. Distinctive:

    no operation infers a target from ordering, priority, Project fields, or recommendation.

    line 211
  13. Distinctive:

    After mutation, re-read the singleton and require exact intended state.

    line 213
  14. Distinctive:

    remove closed Wayfinders from focus.

    line 319
  15. Distinctive:

    remove focused Wayfinders with an open direct map blocker.

    line 320
  16. Distinctive:

    if the resulting set has cardinality 0..1, clear parallel authorization.

    line 322
  17. Distinctive:

    if cardinality remains >1, require the existing authorization to match the exact set.

    line 323
  18. Distinctive:

    Do not compensate for a failure by rewriting another dependency, hierarchy, focus state, or Project projection.

    line 358

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Project Delivery Management

Coordinate delivery across independent Wayfinder efforts without replacing lifecycle owners.

This skill owns only:

  • the current focused Wayfinder set;
  • exact human authorization for parallel focus;
  • current Wayfinder-frontier derivation;
  • cross-Wayfinder dependency placement/removal;
  • deterministic reconciliation after authoritative lifecycle changes;
  • delivery guards for Wayfinder-managed work.

It does not own semantic decisions, Specs, tickets, implementation, verification, review, Project projection, or same-lineage dependencies.

Session independence

Recover every correctness-critical input from the explicit invocation and durable tracker state. Conversation state, Project fields, priority, issue ordering, branch activity, and recent activity are never delivery authority.

Executable reconcile / guard boundary

Reconciliation and guard classification are executable repository behavior owned by:

python -m scripts.project_delivery reconcile --repo <owner/repo>
python -m scripts.project_delivery guard --repo <owner/repo> --wayfinder <issue-number>

Default-branch execution source

scripts.project_delivery is delivery control-plane runtime, not Spec candidate content. Resolve and fetch the repository's current remote default-branch tip before executing reconcile or guard. Execute those commands from a clean detached checkout/worktree (or an equivalently isolated clean checkout) at that exact fetched default-branch tip whenever the caller is operating from a different branch, a detached reviewed candidate, or any checkout whose runtime identity cannot be proven equal to the current default-branch tip.

The control-plane checkout is execution-only. Do not checkout, reset, stash, clean, commit, or otherwise mutate the caller's lifecycle worktree merely to obtain current control-plane runtime. Pass repository and Wayfinder identity explicitly to the commands and require the executed scripts.project_delivery blob to come from the proven default-branch tip.

Never copy, cherry-pick, merge, or synchronize scripts/project_delivery.py or its tests into a verified/reviewed Spec branch merely to obtain a workflow-runtime repair. Runtime repairs land on the default branch. A reviewed lifecycle candidate remains unchanged except for synchronization surfaces explicitly permitted by the repository-wide Non-Semantic Workflow-Policy Synchronization rule in AGENTS.md.

If a clean exact default-branch execution plane cannot be proven, fail closed. Do not fall back to the candidate branch's older runtime and do not reproduce the algorithm manually.

These commands are the sole runtime implementation of singleton discovery, current-state parsing, focused-map validation, direct map-blocker reads, deterministic reconciliation, and PROJECT DELIVERY GUARD classification.

The policy below defines the semantics those commands must implement. It is not permission for a caller—or for an agent executing this skill—to reproduce the algorithm with ad hoc gh commands. If the executable boundary is unavailable, fails, or returns malformed output, fail closed. Do not reconstruct an equivalent result manually.

reconcile exits successfully only after a valid no-op or a verified deterministic mutation/readback. guard exits successfully only for ALLOWED; a BLOCKED guard is a non-zero result and never changes focus.

Human focus operations and cross-Wayfinder dependency operations remain owned by this skill as described below; this executable boundary currently owns only reconcile and guard.

Canonical control artifact

Require exactly one open GitHub issue labeled exactly:

project-delivery:management

Discover the singleton by GitHub label metadata across open and closed issues. The label is the discovery key; issue title/body text is not. Use a label-filtered issue listing/API path with complete pagination, then verify exact label membership on every returned issue.

Do not use GitHub search syntax, body/title matching, Project fields, remembered issue numbers, or a previously observed singleton as a substitute for canonical discovery. In particular, do not run ad hoc queries such as gh search issues ... in:body to locate the control artifact. If the available client path cannot prove complete label-filtered pagination, return invalid control state and fail closed rather than trying another heuristic discovery method.

Zero, multiple, or closed matching issues are invalid current repository state and fail closed. Creation or repair of the control artifact is repository administration outside this runtime skill.

The singleton body contains exactly one current-state block:

## Current Delivery State

**Focused Wayfinders:** None
**Parallel authorization:** None

Focused Wayfinders is None or issue references sorted by issue number. Parallel authorization is None for cardinality 0..1 and otherwise the URL of the exact durable human authorization comment for that focused set.

Do not persist frontier, queue order, blocked state, priority, lifecycle stage, Project fields, or dependency registries in the singleton.

Invocation boundary

Human operations

Only an explicit human invocation may make a discretionary focus choice:

focus <Wayfinder>
switch-focus <Wayfinder>
parallel-focus <Wayfinder>...
status
reconcile

Every focus-changing operation names exact Wayfinder issue numbers or URLs.

For reconcile, use the executable command defined above rather than reimplementing the operation inline.

Internal composition

A lifecycle owner may invoke:

guard <Wayfinder>
dependency ensure <consumer> blocked-by <blocker>
dependency remove <consumer> blocked-by <blocker>
reconcile

Internal composition may never establish focus from empty state, switch focus, add a map to parallel focus, broaden parallel authorization, or invent a dependency.

Deterministic removal of completed or directly ineligible focused maps is reconciliation, not a discretionary focus choice.

For guard and reconcile, internal composition means invoking the executable commands above and consuming their exact output/exit status.

Caller boundary

Lifecycle callers consume this skill's executable result; they do not reproduce its control-state or guard algorithm inline. Singleton discovery, focus validation, Wayfinder-frontier derivation, reconciliation, and guard classification belong to scripts.project_delivery for these operations.

A caller must not compensate for a failed command by performing independent gh search, gh api, GraphQL, body/title matching, Project queries, or remembered-state checks and then declaring an ALLOWED result itself. A failed, incomplete, ambiguous, or malformed command result is a blocked guard.

Canonical Wayfinder frontier

Discover current open wayfinder:map issues and read each complete native blocked by relationship set. Truncated blocker data fails closed.

A map is frontier-eligible exactly when it is open and has zero open direct native map blockers. Lower-level Spec/ticket blockers do not remove a map from the project-level frontier.

Never derive frontier membership from Project fields, priority, issue order, assignees, branch state, recency, or activity.

Validate current focus

Parse the singleton and require:

  • every focused issue is a current canonical Wayfinder map;
  • every focused map is frontier-eligible;
  • cardinality greater than one has one exact matching parallel authorization comment;
  • cardinality zero or one has Parallel authorization: None.

Invalid current focus fails closed before any substantive guard or focus mutation.

Human focus operations

Before changing current focus, append:

## Project Delivery Focus Authorization

**Operation:** focus | switch-focus | parallel-focus
**Focused Wayfinders:** #<n>[, #<n>...]
**Authorization source:** explicit human invocation

If that comment cannot be persisted, do not mutate the singleton.

Rules:

  • focus requires current focus empty and target frontier-eligible;
  • switch-focus requires target frontier-eligible and replaces the current set;
  • parallel-focus requires every exact target frontier-eligible and records that exact set;
  • no operation infers a target from ordering, priority, Project fields, or recommendation.

After mutation, re-read the singleton and require exact intended state.

Guard

Execute:

python -m scripts.project_delivery guard --repo <owner/repo> --wayfinder <issue-number>

The command requires:

  1. a valid canonical singleton/current focus;
  2. target is a current canonical Wayfinder map;
  3. complete direct blocker state is readable;
  4. target is frontier-eligible;
  5. target belongs to the current focused set.

Successful output is exactly:

PROJECT DELIVERY GUARD: ALLOWED
Wayfinder: #<n>
Focused set: <exact set>

A blocked command emits:

PROJECT DELIVERY GUARD: BLOCKED
Wayfinder: #<n>
Reason: <not frontier-eligible | not focused | invalid control state | unreadable blockers>

and exits non-zero. A blocked guard never changes focus. No caller may synthesize either receipt itself.

Cross-Wayfinder dependencies

A cross-Wayfinder dependency is an exact semantic prerequisite between artifacts governed by different Wayfinder lineages. Native GitHub blocked by relationships are durable dependency truth; this skill owns only the semantic placement decision for cross-lineage edges and delegates mechanics to $github-issue-dependencies.

Recover lineage

Resolve each endpoint to its exact governing Wayfinder from durable tracker provenance:

  • map -> itself;
  • decision -> native Wayfinder parent;
  • Spec -> current Wayfinder source/remediation governance applicable to the relationship;
  • implementation/review artifact -> parent lineage.

Ambiguous lineage fails closed. Same-lineage relationships return to the owning lifecycle rather than being mutated here.

Lowest accurate boundary

For dependency ensure, require durable semantic evidence for the exact prerequisite and choose the narrowest authoritative consumer/blocker pair whose completion boundary makes the prerequisite true.

Ask:

  1. does completion of this blocker fully satisfy this prerequisite?
  2. is there a narrower authoritative endpoint that avoids blocking unrelated work?

An unresolved answer returns AMBIGUOUS DEPENDENCY PLACEMENT without mutation.

Wayfinder -> Wayfinder is valid only when the downstream destination as a whole cannot advance safely until the upstream Wayfinder is complete and no narrower edge is sufficient.

Cycle guard

Before adding consumer blocked-by blocker:

  • reject self-dependency;
  • traverse the complete native blocker graph reachable from the proposed blocker;
  • fail closed on unreadable/truncated graph data;
  • reject when the consumer is reachable from the blocker.

Ensure/remove

dependency ensure re-reads the current edge immediately before mutation, treats an exact existing edge as idempotent success, delegates one exact add to $github-issue-dependencies, verifies it, then runs deterministic focus reconciliation via scripts.project_delivery reconcile.

dependency remove requires durable authority that the prerequisite no longer applies or was established in error. Closed blocker state alone is not removal authority. Re-read the edge, treat absence as idempotent success, delegate one exact removal, verify it, then runs deterministic focus reconciliation via scripts.project_delivery reconcile.

A newly added map-level blocker may force a focused map out of focus. Report that release and valid explicit human focus choices; never auto-select a replacement.

Reconcile

Execute:

python -m scripts.project_delivery reconcile --repo <owner/repo>

The command applies only consequences forced by current canonical state:

  • remove closed Wayfinders from focus;
  • remove focused Wayfinders with an open direct map blocker;
  • preserve still-open frontier-eligible focused maps;
  • if the resulting set has cardinality 0..1, clear parallel authorization;
  • if cardinality remains >1, require the existing authorization to match the exact set.

Reconciliation never adds focus, chooses a replacement, or changes dependencies merely to preserve focus.

It must re-read and verify the singleton after mutation. Successful output is:

PROJECT DELIVERY RECONCILE: NOOP | UPDATED
Focused set: <exact set>

Invalid or unreadable state exits non-zero. Do not reproduce reconciliation with direct GitHub reads/writes outside the executable boundary.

Deferred Project projection

This skill never invokes $project-tracking as a side effect. Project projection occurs only at the permanent authorized boundaries defined by $project-tracking: completed-Spec reconstruction or an explicit human board-refresh request.

Project lag never changes focus, dependency truth, frontier eligibility, or lifecycle authorization.

Results

Human/status operations report the exact focused set and frontier. Dependency failures use:

PROJECT DELIVERY DEPENDENCY: INVALID
Consumer: <issue>
Blocker: <issue>
Reason: <cycle | ambiguous placement | ambiguous lineage | unsupported inference | incomplete graph | mutation/verification failure>

Do not compensate for a failure by rewriting another dependency, hierarchy, focus state, or Project projection.

Non-goals

$project-delivery-management does not create/repair its control artifact, choose semantic requirements, create lifecycle artifacts, execute delivery work, maintain a duplicate Wayfinder registry, persist a queue, infer focus from Project state, or provision Project schema.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.