@mriekki/project-forge 3.0.0 → 4.1.0

package/assets/generated/core/core/agents/coach.agent.md

@@ -1,69 +0,0 @@
----
-name: Coach
-description: Optional guided engineering-learning agent using actual repository context for concepts, code walkthroughs, debugging, coding/SQL/system-design drills, interviews, diagrams, and resources.
-user-invocable: true
-disable-model-invocation: true
----
-
-# Coach
-
-You are the optional engineering-learning perspective.
-
-Coaching is never required to start, continue, review, accept, deliver, merge, or complete engineering work.
-
-## Core behavior
-
-- Do not edit production code or implement fixes for the developer.
-- Do not invoke subagents.
-- Do not silently broaden product scope.
-- Do not pin/request/switch to a premium model automatically.
-- Read minimum relevant context.
-- Use actual repository code, requirements, tests, diffs, incidents, and decisions when useful.
-- Ask one material question at a time.
-- Continue automatically until stop/natural completion.
-- Adapt difficulty to demonstrated understanding.
-- Challenge shallow explanations.
-- Distinguish actual implementation/understanding from AI-generated work or study.
-
-## Depth and levels
-
-Depth: Light, Focused, Deep, Broad, or Coach recommends.
-
-Levels:
-
-```text
-L1 Recognize
-L2 Explain
-L3 Trace
-L4 Apply / Debug
-L5 Defend / Design
-L6 Interview Ready
-```
-
-Do not inflate mastery.
-
-## Modes
-
-Support concept learning, real-code walkthroughs, debugging, coding/DSA, SQL/database, design defense, system design, interview drills, gap assessment, learning paths, diagrams, and optional external resources.
-
-For a structured walkthrough of a changed implementation across a Git/PR/commit change set, route to `/code-walkthrough` when available. Use Coach directly for ad-hoc code explanation or deeper concept exploration.
-
-Use installed learning assets when present; otherwise coach directly from the repository/context.
-
-## Adaptive questioning
-
-Weak answer → teach/simplify/own-words explanation.
-
-Solid answer → application/edge case.
-
-Strong answer → tradeoff/debug/design.
-
-Very strong answer → scale/change assumptions/interviewer pressure.
-
-## Resources and progress
-
-Prefer official documentation and a small number of current high-quality tutorials/resources. External material is optional.
-
-Only update an optional learning-progress tracker with explicit human choice.
-
-Never turn study or personal-project understanding into false claims of professional experience.

package/assets/generated/core/core/skills/core-sync/SKILL.md

@@ -1,184 +0,0 @@
----
-name: core-sync
-description: Direct Core-to-consumer synchronization for component-only consumers; package-managed consumers are routed to /project-forge-update so umbrella and component baselines remain coherent.
-argument-hint: "[optional local Core path]"
-user-invocable: true
-disable-model-invocation: true
----
-
-# Core Sync
-
-`/core-sync` is the direct component synchronization path for consumers that are managed directly by `CORE_BASELINE.json` **without** an umbrella `PROJECT_FORGE_BASELINE.json`.
-
-For package-managed consumers, `/project-forge-update` is authoritative.
-
-Invocation starts read-only. Direct component synchronization must never make a package-managed consumer disagree with its recorded Project Forge package provenance.
-
-## 1. Classify the consumer before doing anything else
-
-From the consumer repository read, when present:
-
-- `PROJECT_FORGE_BASELINE.json`;
-- `CORE_BASELINE.json`;
-- `.github/project-forge-workspace.json`;
-- `.github/project-forge-core-sync.json`;
-- current Git status, branch, remotes, and default branch when observable.
-
-### Package-managed consumer
-
-If `PROJECT_FORGE_BASELINE.json` exists:
-
-```text
-PACKAGE-MANAGED PROJECT FORGE CONSUMER
-Direct Core sync: NOT PERMITTED
-Next: /project-forge-update
-```
-
-Stop before refreshing a Core checkout, running `tools/package/sync.py`, creating a sync branch, or sending a remote `[sync-core]` request.
-
-The umbrella package updates Core and Deployment components together and refreshes `PROJECT_FORGE_BASELINE.json`, `CORE_BASELINE.json`, and `DEPLOYMENT_BASELINE.json` coherently. A Core-only sync would bypass that contract.
-
-### Component-only Core consumer
-
-If `PROJECT_FORGE_BASELINE.json` is absent and a valid `CORE_BASELINE.json` exists, continue with the component-managed path below.
-
-If neither baseline exists, report `CORE SYNC BLOCKED`; do not invent provenance or initialize a consumer implicitly.
-
-## 2. Establish the component-only Core baseline
-
-Run the repository-local integrity check before planning an update:
-
-```text
-python tools/project-forge-core/check-core-baseline.py --root .
-```
-
-Stop if the managed overlay has unexplained local drift, missing managed files, or invalid baseline metadata.
-
-Resolve from `CORE_BASELINE.json`:
-
-- canonical Core repository;
-- currently accepted Core commit/version;
-- distribution name;
-- managed-path ownership/hashes.
-
-## 3. Resolve the Core source safely
-
-Check local candidates in this order:
-
-1. an explicit Core path supplied by the human;
-2. an already-open workspace folder that unambiguously resolves to the recorded Core repository;
-3. the sibling checkout derived from the Core repository name, normally `../project-forge-core`.
-
-Do not broadly scan the filesystem. A local Core checkout is an optimization, not a prerequisite.
-
-A local candidate is usable only when it is the recorded Git repository and its state can be inspected safely.
-
-If no usable local Core checkout exists, use the configured remote provider from `.github/project-forge-core-sync.json` when available. Do not ask the developer to clone Core merely to satisfy `/core-sync`.
-
-## 4. Classify a local Core checkout
-
-Before modifying a local Core checkout inspect:
-
-```text
-git -C <core-path> status --short --branch
-git -C <core-path> branch --show-current
-git -C <core-path> remote -v
-git -C <core-path> branch -vv
-```
-
-It may be refreshed automatically only when clean, on its normal accepted/default branch, backed by an unambiguous upstream, and fast-forward-safe.
-
-Never auto-stash, merge, rebase, reset, clean, force-update, or discard Core work.
-
-If the checkout is dirty, ahead, diverged, intentionally pinned, or ambiguous, preserve it unchanged and prefer the configured remote provider when available.
-
-## 5. Present one bounded component-sync choice
-
-Use the host-native **single-select structured choice UI** when available because exactly one next action is authorized. In VS Code use the native question surface such as `vscode_askQuestions`. Preserve the consequence labels and show the recommended choice. Use a numbered text list only when structured choice UI is unavailable.
-
-For a safe local source, show the evidence:
-
-```text
-CORE SYNC READY
-
-Consumer baseline: <commit/version>
-Source: LOCAL <core-path>
-Distribution: <distribution>
-```
-
-Then offer:
-
-- `Sync the component-only Core baseline` `[GIT + FILE WRITE]` — `RECOMMENDED`
-- `Keep inspecting only` `[READ ONLY]`
-- `Stop` `[NO ACTION]`
-
-For a configured remote source, show:
-
-```text
-CORE SYNC READY
-
-Consumer baseline: <commit/version>
-Source: REMOTE PROVIDER
-Provider: <provider repository>
-```
-
-Then offer:
-
-- `Request remote Core sync` `[REMOTE WRITE]` — `RECOMMENDED`
-- `Keep inspecting only` `[READ ONLY]`
-- `Stop` `[NO ACTION]`
-
-The selected choice does not authorize merge, release publication, or deployment.
-
-## 6. Local component path
-
-After `Sync the component-only Core baseline` is selected:
-
-1. Refresh Core remote state.
-2. Reclassify the accepted/default Core branch.
-3. Fast-forward it only when safe.
-4. Run canonical Core sync preview using the distribution recorded by the baseline.
-5. Stop on `LOCAL_DRIFT`, `CONFLICT`, `LOCAL_MISSING`, `UNTRACKED_CONFLICT`, or an unaccepted `RETIRED_PATH`.
-6. If the consumer is on its default branch, create/switch to a short-lived branch such as `chore/sync-core-<version-or-short-sha>`.
-7. Apply only safe Core additions/updates and refresh `CORE_BASELINE.json` using canonical `tools/package/sync.py`.
-
-Do not manually copy managed files as a substitute for the canonical tool.
-
-## 7. Remote component path
-
-Remote orchestration is consumer configuration. Read `.github/project-forge-core-sync.json` and require its configured provider contract, for example `github-issue-control-plane` with an owner/repository title template and an empty body.
-
-Create exactly the configured request. Do not put product requirements, baseline JSON, source code, secrets, or other private consumer details into a public request.
-
-The provider is expected to validate target authorization, obtain its own short-lived credentials, run canonical Core sync, refuse unsafe drift/conflicts, publish a short-lived consumer branch/PR, and observe consumer CI.
-
-If the provider cannot satisfy that contract, report `REMOTE SYNC UNAVAILABLE`; do not silently clone Core or invent another synchronization mechanism.
-
-## 8. Verification
-
-For a local apply run:
-
-```text
-python tools/project-forge-core/check-core-baseline.py --root .
-git status --short --branch
-git diff --stat
-git diff -- CORE_BASELINE.json
-```
-
-Confirm exact Core provenance, managed hashes, consumer-owned preservation, and intended branch scope. Present the meaningful diff and recommend `/deliver` after human acceptance.
-
-For a remote path, report the resulting PR and exact Core commit when observed. Merge remains the normal explicit final gate.
-
-## 9. Boundaries
-
-`/core-sync` never:
-
-- directly synchronizes Core when `PROJECT_FORGE_BASELINE.json` exists;
-- uses direct Core sync as a substitute for `/project-forge-update`;
-- modifies ambiguous local Core state;
-- treats managed consumer drift as disposable;
-- publishes Core or Project Forge package releases/tags;
-- merges the consumer sync PR;
-- deploys production.
-
-If reusable Core behavior itself is wrong, fix Core canonically through `/upstream-fix`; then adopt it through the update channel appropriate to the consumer's provenance model.

package/assets/generated/core/core/skills/developer-env-mode/SKILL.md

@@ -1,231 +0,0 @@
----
-name: developer-env-mode
-description: "Converge and verify the developer workstation for local-only or remote-enabled work. Mode changes become effective only after the selected readiness contract passes."
-argument-hint: "status|local|remote"
-user-invocable: true
-disable-model-invocation: true
----
-
-# Developer Environment Mode
-
-`/developer-env-mode` manages the current workstation's operational development mode. It is not a deployment command and it does not weaken Staging or Production gates.
-
-Supported intents:
-
-```text
-/developer-env-mode status
-/developer-env-mode local
-/developer-env-mode remote
-```
-
-The governing invariant is:
-
-```text
-MODE != preference
-MODE = verified operational state
-```
-
-Never record a requested mode as ready until its readiness contract passes. If convergence fails, preserve the prior ready mode when one exists and report the blocker.
-
-## 1. Resolve repository and package provenance read-only
-
-From the repository root inspect, when present:
-
-- `PROJECT_BOOTSTRAP.json`;
-- `PROJECT_FORGE_BASELINE.json` and component baselines;
-- `DEV_ENVIRONMENT.json`;
-- application setup/build/test commands and project-owned persistence configuration;
-- deployment topology and generated deployment tooling;
-- Git status so unrelated work is preserved.
-
-For package-managed consumers, verify managed files are coherent before relying on distributed Core or Deployment tooling. Route managed drift to `/project-forge-update` rather than overwriting it.
-
-Do not require a Bootstrap/Core/Deployment Kit source checkout for normal consumer use.
-
-## 2. Keep current mode state workstation-local
-
-Mode state is user/workstation state, not repository authority. Store it outside the repository under the user-scoped Project Forge directory, using a repository-scoped location such as:
-
-```text
-~/.project-forge/workspaces/<owner>/<repo>/developer-environment.json
-```
-
-Do not commit this state. Do not store credentials, private keys, target trust stores, database contents, or secret values in it.
-
-Record enough non-secret evidence to distinguish requested mode from readiness, for example:
-
-- mode;
-- ready/not-ready;
-- verification timestamp;
-- source revision when available;
-- build/test state or fingerprint;
-- local database state when applicable;
-- local runtime health when applicable;
-- remote target/access readiness summary when applicable.
-
-A later `status` check must be allowed to report that the recorded mode is no longer ready when Docker stops, tools drift, the build becomes stale, the local database is missing/incompatible, or remote access disappears.
-
-## 3. `status` is read-only
-
-`/developer-env-mode status` performs no setup writes. Inspect current workstation evidence and live prerequisites, then report both the selected mode and current readiness.
-
-Prefer a compact result such as:
-
-```text
-DEVELOPER ENVIRONMENT
-
-Selected mode: LOCAL
-Readiness: NOT READY
-
-Docker ........ READY
-Build ......... STALE
-Tests ......... READY
-SQLite ........ READY
-Runtime ....... HEALTHY
-Remote access . UNAVAILABLE
-
-NEXT
-/developer-env-mode local
-```
-
-Do not silently repair state during `status`.
-
-## 4. `local` means converge a complete local development environment
-
-Selecting `local` authorizes bounded, non-destructive workstation setup needed to make the current repository usable locally. It does not authorize destructive database reset, deletion of unrelated Docker state, remote publication, remote deployment, or Production writes.
-
-Converge in this order.
-
-### A. Workstation prerequisites
-
-Verify the current OS is supported by repository configuration. Use repository setup/doctor tooling when present to verify required tools and versions.
-
-For Docker-based local execution require a working Docker CLI/engine. Prefer repository-distributed Deployment Kit commands when `DEPLOYMENT_BASELINE.json` proves they are installed.
-
-### B. Dependencies and restore
-
-Run repository-defined dependency restore/setup commands when missing or stale. Preserve pinned versions and project conventions. Do not substitute arbitrary global tooling when the repository defines a supported path.
-
-### C. Local persistence
-
-If the application uses SQLite for local development:
-
-1. resolve the project-owned database filename/container path and migration/initialization contract from repository configuration/docs/code;
-2. prefer the installed Deployment Kit local SQLite ensure/status primitive when available for workstation-owned persistent storage;
-3. when the database is absent, create the owned local SQLite file/directory non-destructively;
-4. run the repository-provided migration/schema initialization needed to make that database usable;
-5. verify the resulting database can be opened and that the application-required schema/migration state is current when the repository provides such a check.
-
-If an existing SQLite database is corrupt, incompatible, or has unexpected ownership/schema state, **STOP**. Never delete, replace, reset, or migrate destructively merely to make mode convergence pass. Present the exact recovery/reset decision separately.
-
-Do not assume every project uses SQLite. Other persistence requires an explicit repository-owned local setup contract.
-
-### D. Build and tests
-
-Run the repository's required local build and test commands. A missing or stale build is a normal convergence condition; rebuild it.
-
-If build or required tests fail, report `LOCAL MODE NOT READY` and do not mark the mode ready.
-
-When the project policy says application validation is local-only, GitHub publication/PR activity does not replace this local build/test evidence.
-
-### E. Local immutable Docker artifact
-
-When the local runtime is Docker-based, build the application image locally using repository-owned commands. Resolve an immutable local image identity.
-
-The standard Deployment Kit workstation adapter may accept either:
-
-- an exact registry digest (`name@sha256:...`), or
-- a local Docker image ID (`sha256:<64 hex>`) for workstation-only execution.
-
-Never use a mutable tag as the final deployed identity. A local image ID is valid only for workstation placement and is not remote-release evidence.
-
-### F. Workstation runtime
-
-Converge the local application runtime through the repository-distributed workstation adapter when available:
-
-```text
-placement: workstation
-isolation: container
-exposure: loopback
-```
-
-Keep exposure loopback-only. Mount the project-owned local SQLite persistence directory when required. Verify the declared health endpoint and any required local smoke check.
-
-Do not resolve SSH targets, publish images, create public routes, or deploy Staging/Production while entering local mode.
-
-### G. Commit local mode only after readiness passes
-
-Only after prerequisites, persistence, build, tests, runtime, and health requirements pass, write the workstation-local mode state as ready.
-
-A successful summary should distinguish local evidence from remote evidence:
-
-```text
-LOCAL DEVELOPER ENVIRONMENT READY
-
-Build ........ READY
-Tests ........ READY
-Docker ....... READY
-SQLite ....... READY / NOT APPLICABLE
-Application .. HEALTHY
-Remote deploy. DISABLED BY MODE
-```
-
-## 5. `remote` means verify remote-enabled capability, not deploy
-
-Selecting `remote` authorizes bounded, non-destructive checks/setup needed to prove that the current workstation can work with the repository's configured remote non-Production environment(s). It does **not** publish an artifact or deploy an application.
-
-Verify as applicable:
-
-- normal local developer prerequisites still needed to build/test the project;
-- repository deployment topology contains a non-deferred remote environment;
-- exact target/provider binding exists when required;
-- workstation-to-target trust/access is valid;
-- target OS/runtime/platform readiness is valid;
-- persistence/readiness prerequisites can be inspected safely;
-- GitHub/registry access needed for a later release/publish step is available;
-- repository release/deployment tooling and baselines are coherent.
-
-For the standard remote-SSH path preserve strict host identity. Unknown or changed host identity is a stop condition. Never fall back to another environment or host.
-
-Do not require a Production target merely to enter remote mode. Do not weaken Production authorization because remote mode is ready.
-
-Only after the selected remote readiness checks pass, record `remote` as ready.
-
-Then report the next explicit operation, typically:
-
-```text
-/deployment-readiness <environment>
-```
-
-A later `/deploy <environment>` remains separately gated.
-
-## 6. Fail closed on destructive or ambiguous repair
-
-Automatic convergence may safely create missing local directories, dependency caches, build outputs, a new owned SQLite file, migrations that the project defines as normal forward initialization, and a new owned local application container.
-
-Stop for a separate explicit decision before:
-
-- deleting/resetting an existing database;
-- destructive migration or rollback;
-- replacing unexplained persistent data;
-- deleting unrelated containers/images/volumes;
-- publishing an artifact remotely;
-- rebinding a target;
-- weakening host verification;
-- deploying Staging or Production;
-- changing public/LAN exposure.
-
-## 7. Relationship to other Project Forge commands
-
-`/developer-env-mode` prepares a workstation and establishes current operational readiness.
-
-It does not replace:
-
-- `/project-forge-update` for managed Project Forge package changes;
-- project setup/doctor tooling;
-- `/start-work` for implementation authorization;
-- `/deployment-readiness` for environment-specific pre-deploy evidence;
-- `/deploy` for deployment authorization/execution;
-- `/tear-down` for destructive cleanup.
-
-Mode switching never implies merge, release publication, Staging deployment, or Production deployment.

package/assets/generated/core/core/skills/grill-with-docs/SKILL.md

@@ -1,88 +0,0 @@
----
-name: grill-with-docs
-description: Continuously challenge requirements/design and reconcile resolved decisions into permitted authoritative/supplemental documents or proposed external-work-item updates.
-argument-hint: "<work-item ID, external key, document, plan, or topic>"
-user-invocable: true
-disable-model-invocation: true
----
-
-# Grill With Docs
-
-This is the documentation-aware form of `/grill-me`.
-
-## 1. Resolve authority
-
-Read `.github/project-forge-workspace.json` when present.
-
-Determine:
-- authoritative work-item source,
-- which local documents are authoritative/supplemental/read-only/not-used,
-- whether an external write integration is actually available and permitted.
-
-Never assume Product/Feature Briefs exist. Never assume `Jira Epic == Feature Brief`.
-
-## 2. Continuous grilling
-
-Ask one material question at a time and challenge:
-- ambiguous outcomes,
-- missing domain/engineering rules,
-- contradictory requirements,
-- lifecycle/destructive behavior,
-- data integrity/concurrency,
-- failure behavior,
-- accessibility/UX implications when relevant,
-- architecture/operational tradeoffs,
-- testability.
-
-When the challenge is a bounded decision with a small credible option set, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md` and explain important tradeoffs. Use host-native single-select UI for mutually exclusive alternatives when available, and multi-select only when several choices may be valid together. When the purpose is to expose or strengthen the human's reasoning, ask open-ended first; introduce options or hints later only when useful as scaffolding.
-
-Cadence:
-
-```text
-question
-→ human answer
-→ challenge/analyze
-→ reconcile the resolved decision when already authorized
-→ next material question
-```
-
-Do not ask whether to continue after every answer.
-
-## 3. Reconcile to the right authority
-
-When a decision is resolved:
-- update an existing permitted local authority/supplement only when the current session authorizes document edits;
-- if Jira/GitHub/another external system is authoritative and no permitted write integration is available, accumulate a concise `PROPOSED EXTERNAL WORK-ITEM UPDATE`;
-- if a permitted external write integration exists, require an explicit `[EXTERNAL WRITE]` choice before writing externally;
-- never create a competing local source merely to store an answer.
-
-For local-document models, common homes are:
-- brief: high-level scope/outcome/major rule,
-- combined requirements: detailed user/engineering behavior and testable scenarios,
-- decisions: resolved work-item decision/basis,
-- ADR: only a meaningful cross-cutting architecture decision.
-
-## 4. Editing authorization
-
-Invocation alone does not imply broad document-write permission.
-
-When document changes are needed, present a bounded **single-select structured choice** through the host UI when available. In VS Code use the native question surface such as `vscode_askQuestions`. Relevant choices are:
-
-- `Continue grilling only` `[READ ONLY]`
-- `Reconcile resolved decisions during this session` `[MODIFIES DOCS]`
-- `Stop` `[NO ACTION]`
-
-Use a numbered text list only when structured choice UI is unavailable. After `Reconcile resolved decisions during this session` is selected, focused updates to the permitted current work-item documents are authorized for the active session. Do not ask again after each answer.
-
-Pause only when a new answer would change higher-level approved scope, contradict another authority/ADR, or require a new cross-cutting decision.
-
-## 5. Stop boundary
-
-Do not implement production code.
-
-At natural completion summarize:
-- decisions resolved,
-- documents/proposed external updates changed,
-- remaining conflicts/open items.
-
-If systematic detailed coverage is still needed, recommend `/refine-requirements`.