man

mancode mode: man

Purpose: clarify, plan, implement, verify, and review governed work.

Enter through mancode

Before the first command, use ./node_modules/.bin/mancode when it exists, otherwise mancode; check that selected binary with --version once and never mix binaries or versions. In every command below, replace the literal mancode with that selected binary path when the local binary exists.

1. Reuse a mancode status --brief --json snapshot already obtained in this conversation. Only when none exists, run it once from the project root. Never read or write the legacy authority file.
2. If the request is only a read-only project orientation, introduction, explanation, or summary, inspect the repository and answer directly without creating an actor, session, TaskRef, or workflow. Do not turn an orientation request into a plan_only workflow.
3. Only for requested governed task work, if identity.actorId is absent, ask for a display name and run mancode team identity create --name "<display name>".
4. Reuse session.sessionId when present. If status has no current session, reuse an explicit session ID already retained in this conversation. Only if neither exists, run mancode context session new --client cursor exactly once and retain the returned session ID. Use --client cursor on every command that uses this session.
5. Reuse the current TaskRef. To bind a supplied existing task, run mancode context resume <namespace:ULID> --session <id> --client cursor.
6. For an existing task, read only the needed Context Pack with mancode context show --purpose plan --session <id> --client cursor; include --task <namespace:ULID> when it is not yet bound. For a new task, create it through the mode action first, then read the returned TaskRef's Context Pack.

Mode action

• For a read-only project orientation, inspect and answer directly; do not create governance records.
• For a new task, run mancode workflow create man "<task>" --session <id> --client cursor.
• Read .mancode/shared/context/glossary.json when it exists and prefer its confirmed terms in clarification, requirements, plans, reports, and naming.
• Before requirements, run a bounded read-only decision-impact discovery: test the operator's factual premise against repository evidence, inspect the end-to-end user goal and common domain failure/edge paths, and retain at most three findings with stable IDs F-1 through F-3 and type premise, scope, technical, risk, or acceptance. Mark each as repository_fact or domain_hypothesis; an unverified domain hypothesis becomes a focused question, never a fact. Discovery produces evidence and recommendations, never execution authority.
• Before writing requirements, inspect the relevant project facts and implementation, then run a decision-readiness gate covering both clarity and soundness. Treat the request as ready only when the goal, in-scope/out-of-scope behavior, acceptance boundary, semantic owner/source of truth, and decision-changing constraints are supplied and consistent with evidence, verifiable from the repository, or explicitly recorded as safe defaults. A supplied instruction is not automatically correct. Do not ask ceremonial questions or manufacture alternatives when the request is already clear and sound.
• Classify unresolved decisions as blocking, recommendable, or defaultable. Ask and wait for blocking decisions; for recommendable decisions, present 2–3 bounded options with tradeoffs and one clear recommendation; use a default only when it is low-impact, reversible, consistent with repository conventions, and recorded with its reason. Give every F-ID one type-directed disposition: Accepted scope or behavior findings enter confirmedScope and the matching acceptanceCriteria; accepted technical choices enter technicalDecisions; only low-impact reversible details enter defaults; Only explicitly excluded behavior enters excludedScope. An unaccepted proposal remains unauthorized without being copied into every field.
• If any unresolved ambiguity could change the goal, scope, user-visible behavior, acceptance, architecture, data, security, compatibility, owner, or source of truth, stop before requirements finalization, explain the missing decision, ask focused questions, and wait for the user answer. Ask in as many batches as needed, do not repeat answered questions, and never turn an unverified assumption into confirmed scope or confirmed coverage.
• Before waiting on a blocking answer, persist the known facts, partial decisions, and each open question with mancode workflow requirements <namespace:ULID> draft --file <requirements.json> --expected-revision <n> --session <id> --client cursor. A draft may leave scope, coverage, technical decisions, or acceptance incomplete only while blockingUnknowns names the open decisions. After every answer, update the draft or finalize it so another session can resume the exact clarification state.
• If an explicit direction conflicts with repository evidence or creates a hard-risk authentication, payment, sensitive-data, deletion, migration, public-API, untrusted-input, concurrency, infrastructure, or irreversible change, stop before requirements finalization. Show the evidence and impact, recommend a safer path, ask for a focused confirmation or choice, and wait; clarity does not waive risk.
• After the user answers, summarize the resolved requirements and any remaining defaults. Continue only when no decision-changing blocking unknown remains; otherwise keep the task in clarification and ask again.
• Write requirements as semantic JSON with version: 1, a non-empty goal, non-empty confirmedScope, and the arrays excludedScope, technicalDecisions, defaults, and blockingUnknowns. Every array item must be a non-empty string; an array may be empty except confirmedScope, and technicalDecisions must be non-empty whenever technical_stack applies.
• coverage must contain exactly one item for each dimension: platform, core_scope, technical_stack, data_and_persistence, performance, compatibility, and security. Each item has the shape { "dimension": "platform", "status": "confirmed", "rationale": "..." }; status is exactly confirmed, defaulted, or not_applicable, and rationale is non-empty.
• acceptanceCriteria must contain at least one required item shaped as { "id": "AC-1", "description": "...", "required": true, "method": "automated" }; method is exactly automated, manual, or hybrid.
• Finalize requirements with mancode workflow requirements <namespace:ULID> finalize --file <requirements.json> --expected-revision <n> --session <id> --client cursor.
• Let mancode assign internal IDs and digests; do not invent canonical IDs or digests in the semantic input.
• Make the plan name a user-visible implementationScope with non-empty repo-relative include, plus exclude and modules; include is the file-write upper bound, exclude wins, and modules never authorize files alone. Bind plan and scope atomically with mancode workflow plan <namespace:ULID> revise --expected-revision <n> --file <plan.md> --scope-file <scope.json> --session <id> --client cursor.
• Confirm the current plan with mancode workflow plan <namespace:ULID> confirm --expected-revision <n> --plan-decision <plan_only|governed_execution> --session <id> --client cursor.
• Before editing in governed execution, read the confirmed plan and activeTask.implementationScope, state material assumptions and verifiable success criteria, reuse existing code and dependencies, and implement the smallest direct solution. Every changed line must trace to confirmed behavior or acceptance and stay inside include without matching exclude; do not add speculative features, one-off abstractions, unnecessary configurability, adjacent cleanup, or unrelated defenses.
• If an upgraded, already-running local man task has no executable implementation scope, completion remains blocked. Show the complete replacement boundary and wait for explicit operator approval, then rerun plan revise with the exact unchanged current plan and --scope-file <scope.json>. This compatibility binding only increments plan authority and stales prior review/verification; it must not change the plan, behavior, acceptance, or an already executable boundary.
• During implementation, a newly discovered out-of-scope need authorizes only a read-only NEEDS_REALIGNMENT report until the operator approves reframe. In review, compare the actual diff with canonical functionalScope.inScope / functionalScope.outOfScope, decisions, acceptance criteria, and implementationScope; unauthorized changes are blockers.
• Confirming with --plan-decision plan_only keeps the plan as planned authority and clears this session's active workflow pointer. Resume the TaskRef explicitly before any later governed mutation.
• When new evidence materially invalidates confirmed requirements and the operator explicitly chooses to realign the same local task, resume its TaskRef if needed, generate a fresh canonical checkpoint ULID, and run mancode workflow reframe <namespace:ULID> --expected-revision <n> --checkpoint-id <fresh-ULID> --summary "<reason>" --next-action "<step-2 action>" --session <id> --client cursor. Reframe archives the confirmed requirements and plan, clears the plan decision, and stops at Step 2 with draft requirements. Do not substitute plan revise, scope-change, or workflow update for reframe.
• Read reframe evidence without opening private authority files: mancode workflow archive <namespace:ULID> show <archive-ULID> --json and mancode workflow checkpoint <namespace:ULID> show <checkpoint-ULID> --json.
• Apply verification and review ledgers with their mancode apply --file commands, then use mancode workflow complete <namespace:ULID> --expected-revision <n> --session <id> --client cursor.
• When a new high-frequency domain term emerges, propose it to the operator; only after explicit confirmation register it with mancode context glossary add --term "<term>" --definition "<definition>" --expected-revision <n> --session <id> --client cursor. Never write to the glossary without operator confirmation.