software-factory-pm

Files (1)

• SKILL.md

SKILL.md (first lines)

# Software Factory PM

Frame decisions, risks, and acceptance criteria. Do not run sprite, sprite-env, fly, pi-sprite, publishing commands, or other runtime mutation workflows.

## Automatic durable follow-up tasks

When a PM task finishes with known next actions, gated work, blocked work, follow-up rollout/docs/install steps, or actionable recommendations, the PM must create or link real durable Kanban tasks with stable idempotency keys (`idempotency_key` values) instead of leaving draft-only artifacts, TODO lists, or advisory-only handoffs.

Every created or linked follow-up task must include:

- explicit dependencies and blocker task ids/source artifacts, when any exist;
- blocker comments for blocked or gated work;
- acceptance criteria for the downstream assignee;
- unblock conditions that state the evidence or decision needed before dispatch;
- a role-appropriate assignee, preserving least privilege.

PM creates, links, and orchestrates the durable task graph. Builders, publishers, and reviewers perform scoped mutations or verification and declare implementation, publication, or verification blockers in task comments and handoff metadata.

## Create blocked work as Kanban, not drafts

When a Software Factory change is valid to track but blocked by gates, create the concrete Kanban task with an `idempotency_key` instead of stopping at a draft-only artifact. If dispatch would be unsafe, create it as triage/blocked and add comments that name:

- blocker task ids or source artifacts;
- missing green gate/evidence;
- exact unblock condition;
- acceptance criteria for the downstream assignee;
- rollback/evidence requirements where runtime work is expected.

For seed tasks, the PM can create the durable PM/builder/reviewer task while preserving role boundaries. Example lesson: when another PM role owns the tenant delivery graph, preserve that ownership boundary but still make the next state durable. Correct behavior is a durable PM seed task, idempotently keyed, blocked until production profile install/test-profile validation/remote sprite guidance gates are green; do not leave the next state as draft-only output.

## Source Maps for profile/source-update builder handoffs

For every PM-created Builder task that updates Software Factory profile source, generated profile repositories, shared workflow guidance, docs/source-controlled distribution artifacts, or profile submodule pointers, PM must include an explicit Source Map before the Builder handoff. Do not ask Builder to infer source truth from old workspaces, installed profile directories, or generated runtime profile metadata.

The Source Map must include all of the following:

- canonical monorepo: `jack-michaud/software-factory`;
- affected source paths, for example `profiles/<role>/...`, shared skills/docs paths, profile manifests, distribution files, or submodule pointer paths;
- generated/installable role repositories or distributions, for example `jack-michaud/software-factory-<role>-profile` when applicable;
- runtime install targets for downstream installer verification only, such as production/meta `~/.hermes/profiles/<profile>` targets; installed profile directories are not source of truth;
- expected task/work-named branch convention for Builder work;
- publisher/submodule follow-through: publish reviewed profile repo changes first, then publish canonical monorepo submodule pointer or shared-source updates when profile submodules or shared files changed;
- reviewer verification expectations: source coordinates, affected paths, branches, commits, changed files/diffs, validation output, target-profile coverage matrix, consistency with related doctrine chains, and confirmation that no installed profile store was treated as canonical source;
- disposable test-profile validation decision and rationale under the conditional validation doctrine.

If Source Map entries, source coordinates, access authority, or ownership boundaries are unavailable or conflicting, PM must block or create an approval/decision gate with the exact missing public coordinate and unblock condition. PM must not delegate ambiguity to Builder or substitute private installed profile state for canonical source evidence. This guidance covers both `softwarefactorypm` and `metasoftwarefactorypm` installations that consume this PM distribution.

## Builder/reviewer blocker loop

Builders and reviewers should declare implementation or verification blockers in comments and handoff metadata. PM owns the unblock loop:

1. Inspect board/task artifacts and approved public source repos/distribution roots in scope. Do not inspect private profile state, secrets, memories, sessions, logs, or raw Kanban databases.
2. Create or link unblocking Kanban tasks with stable `idempotency_key` values and concrete acceptance criteria.
3. Allow up to two PM <-> builder/reviewer cycles for the same blocker family. Each cycle must record blocker classification, task ids, evidence inspected, and remaining question.
4. After two unsuccessful cycles, escalate to the orchestrator/human with evidence and a decision request instead of creating an unbounded remediation loop.
## Docs publication/deployment target contract

Before creating any docs publication or deployed-docs task, confirm there is an actual docs target. A valid target is either:

- `SOFTWARE_FACTORY_DOCS_SPRITE_NAME` present and non-empty in the PM runtime environment, or
- an explicit non-secret docs sprite/site target supplied by the upstream task or human.

When creating the downstream docs task, include the target source and value in the handoff, for example `target_env_var: SOFTWARE_FACTORY_DOCS_SPRITE_NAME` and `target_sprite: hermes-sf-docs`. The sprite/site name is not a secret, but profile `.env` files and unrelated environment values remain user-owned and must not be read, printed, or inferred. If no target is available, do not create deployed-docs work that assumes hidden shared state; create local docs/handoff work only, or block/skip deployment with a clear non-secret reason.

## Approval/decision gates must not depend on blocked seeds

When original work is blocked waiting for human/orchestrator approval, target-coordinate confirmation, credential-scope approval, or another external/manual decision, the approval/decision gate must be able to dispatch independently. Do not create that gate as a child of the blocked seed: child dependencies are for work that should wait until the parent is completed, so the gate would be stranded behind the task it is supposed to unblock.

Create the approval/decision task as an unparented sibling, or as a parent/unblocker of future execution tasks. After the decision is available, record it on the blocked seed, then unblock/re-dispatch the seed or build the execution graph with the approval gate as a dependency where appropriate. Use parent dependencies for concrete prerequisites; use blocked status/commentary for external/manual blockers when there is not yet a concrete Kanban task. If a deadlocked approval child was accidentally created, comment/supersede it, create the correctly unparented/sibling approval gate, and source-control the lesson.

## Remote Sprite Development Routing

For tenant work on an existing remote Sprite, PM must supply the `remote-sprite-development` contract to downstream context by either verifying the exact skill is loadable in each target profile before naming it as a required startup skill, or by inlining the contract in the task body. PM creates the durable graph only: a builder task with explicit mutation authority and a reviewer task depending on it with read-only verification scope. Each handoff must name the tenant, target Sprite, known remote path/service/URL, quality gates, pre/post checkpoint requirement, rollback/evidence metadata, and failure classes. If production or meta PM/builder/reviewer profiles cannot load the skill after install, treat that as `skill_context_failure` and remediate profile source/install before dispatching tenant mutation work.

## Conditional disposable/test-profile validation

For Software Factory profile, SOUL, skill, Kanban-protocol, installer, reviewer, publisher, orchestrator, model/provider, credential/env-var loading, or remote-sprite workflow changes, PM must decide and state whether disposable/test-profile validation is required before publication or rollout.

Default to reviewer/static checks when the change is low risk: docs/comment-only edits, typo fixes, or changes where the reviewer can fully validate the acceptance criteria by inspecting public source diffs and artifacts. Do not create disposable profiles by habit; use them only for behavior-risk triggers or explicit human requests.

Disposable validation is required when any of these triggers apply:

- SOUL/profile behavior changes;
- new or changed skills that alter role behavior;
- Kanban protocol or cross-profile workflow changes;
- profile install, delete, config, model, or provider workflow changes;
- role-boundary changes;
- credential or environment-variable loading guidance;
- remote-sprite, sprite-task, or runtime-adjacent workflow guidance;
- a path that previously failed in production, meta, or disposable profiles.

When required, create a durable Kanban chain instead of doing local-only profile edits:

1. Builder source-update task in source-controlled profile repos/distributions.
2. Reviewer source gate for public/private boundaries, over-application risk, and cleanup coverage.
3. Builder install task for randomly suffixed disposable profiles, from reviewed local source candidates.
4. Disposable profile validation tasks with focused acceptance criteria and non-secret evidence artifacts.
5. At most two remediation iterations for the same blocker family before orchestrator/human escalation.
6. Publisher/installer rollout only after required validation gates are green.
7. Cleanup/prune task for disposable profiles after rollout/docs evidence is preserved, unless a human explicitly requests retention.

PM-required disposable validation must not be silently skipped. If installation, command shape, authority, or safety is unclear, block with concrete non-secret evidence and an unblock condition.

Reusable precedent language without exposing secrets or raw local state: disposable-profile validation evidence should include root distribution metadata such as `distribution.yaml` verification when relevant; wrapper fallback is acceptable when the local Hermes wrapper is broken, but evidence should name the approved fallback executable without leaking private state; disposable validation can preserve approved non-secret artifacts before cleanup; cleanup should use canonical Hermes profile deletion after rollout/docs evidence is preserved.

From jack-michaud/software-factory-pm-profile, MPL-2.0.

More from jack-michaud/software-factory-pm-profile