@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: setup
+description: "Guide and execute setup for this workstation/workspace instance, including optional named deployment-environment onboarding and disposable deployment-path proof."
+argument-hint: "[status|repair|local|remote|<environment>]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Setup
+
+Purpose: give the developer one obvious entry point after cloning/opening a Project Forge workspace, whether this is the first workstation for the project or an additional independent workstation for an existing POC.
+
+Normal first use is simply:
+
+```text
+/setup
+```
+
+The skill is the conversational/orchestration layer. Repository-local setup scripts and Deployment Kit commands remain the deterministic machine implementations. Do not duplicate installer, SSH, Docker, deployment, or profile mechanics in the skill when the repository already provides them.
+
+## 1. Resolve this workspace instance
+
+From the repository root inspect only what is needed:
+
+- `DEV_ENVIRONMENT.json`;
+- `DEPLOYMENT_TOPOLOGY.json` when present;
+- `PROJECT_BOOTSTRAP.json` as generation/provenance and initial topology fallback;
+- `SCAFFOLD_PLAN.json` when present;
+- `.github/project-forge-workspace.json` and Project Forge/component baselines when present;
+- `scripts/setup.ps1` on Windows or `scripts/setup.sh` on macOS;
+- current Git branch/status/upstream evidence so setup does not overwrite unrelated work;
+- workstation-local developer-environment evidence when present;
+- the actual workstation OS/platform and machine-local identity needed to describe this workspace instance.
+
+If package-managed Project Forge files are drifted, route that problem to `/project-forge-update`; do not silently replace managed files during setup.
+
+A **workspace instance** is one checkout of one Project Forge project on one developer workstation. Multiple workspace instances for the same project are normal and may be active at the same time.
+
+When project provenance/configuration exists but this computer has no local readiness evidence for the checkout, treat the situation as:
+
+```text
+EXISTING PROJECT — NEW WORKSTATION
+```
+
+Do not require another workstation to be online and do not treat another computer as the project's primary machine.
+
+Detect the current OS automatically. Do not ask the developer which setup launcher to use when the platform can be observed. Prefer a compact preflight such as:
+
+```text
+EXISTING PROJECT — NEW WORKSTATION
+
+Project ............ <project>
+Platform ........... Windows / macOS
+Setup launcher ..... <detected launcher>
+Personal profile ... FOUND / NOT CONFIGURED / DEFERRED
+Local setup ........ READY / NOT CONFIGURED / BLOCKED
+```
+
+A workspace instance owns machine-local state such as local runtime/data, SSH private keys/trust, credential-manager entries, Docker state, and repository-scoped developer-mode evidence. Those values are not synchronized from another workstation.
+
+Git/GitHub is the shared source-code coordination boundary. The personal Project Forge profile is the shared portable non-secret target-definition boundary. Do not invent a central device registry merely to support another workstation.
+
+## 2. Run the generated local setup for the observed OS
+
+Select the launcher for the actual workstation OS:
+
+```text
+Windows  -> .\scripts\setup.ps1
+macOS    -> ./scripts/setup.sh
+```
+
+Do not ask the developer to choose an OS launcher when the OS can be observed.
+
+For normal setup, run the launcher with repository restore enabled when supported:
+
+```text
+setup --restore
+```
+
+For `status`, use the script's read-only check mode when supported:
+
+```text
+setup --check
+```
+
+A manually invoked `/setup` authorizes routine, bounded, non-destructive local setup that the generated script already owns: supported tool installation, VS Code extension installation, dependency restore, personal Project Forge profile initialization, and other declared workstation preparation. Do not add another confirmation merely to start those routine actions.
+
+Stop before destructive replacement, unrelated machine mutation, secret disclosure, or repair outside the declared setup contract.
+
+## 3. Reach local workspace readiness first
+
+The first success target is:
+
+```text
+LOCAL WORKSPACE READY
+```
+
+Remote environments must not block initial local setup unless the approved project explicitly requires a remote dependency for local development.
+
+After the generated setup script passes:
+
+- if application source/runtime already exists, use `/developer-env-mode local` to converge and verify local persistence/build/tests/container/health as applicable;
+- if `SCAFFOLD_PLAN.json` or the approved work-item plan intentionally defers application scaffolding, report local **workspace** readiness without inventing application runtime work;
+- if Docker or another runtime is not required by the current project state, mark it `NOT APPLICABLE`, not failed.
+
+Each workstation normally owns independent local development data. Reproduce schema/migrations/seed behavior as the project defines it; do not silently copy mutable local databases or runtime state from another computer.
+
+## 4. Establish/sync the developer's personal Project Forge profile
+
+When the installed Deployment Kit exposes personal-profile operations, `/setup` should establish the authenticated developer's portable non-secret profile as routine setup state. This repo is per developer, not per POC or workstation.
+
+First inspect profile status and authenticated GitHub login. If the expected private repository is missing, tell the developer what will happen before writing:
+
+```text
+Project Forge will create a private GitHub repository for your portable environment definitions:
+
+  <login>/project-forge-profile
+
+It stores only non-secret target definitions and preferences. SSH private keys,
+passwords, PATs, known-host contents, and machine-local state stay on this computer.
+```
+
+Then invoke the repository-provided deterministic operation within the already-authorized `/setup` action:
+
+```text
+python tools/project-forge-deployment/project-forge-deploy.py environment profile ensure --yes
+```
+
+If the repo already exists and is verified private, reuse it. On an additional workstation, sync/apply the validated portable profile using the repository-provided profile operation when supported, while preserving valid non-conflicting machine-local definitions.
+
+Never import another workstation's private key, known-host contents, PAT, password, local database, Docker credential state, or readiness claim.
+
+If automatic profile creation cannot proceed, use the explicit Bootstrap-like fallback: ask the developer to create the exact private `<login>/project-forge-profile`, reply `created`, then re-verify owner/name/privacy before deterministic initialization. Never ask the developer to paste credentials into chat.
+
+If GitHub is temporarily unavailable, otherwise-ready local development remains valid. Report profile portability as `DEFERRED`.
+
+## 5. Present a guided environment setup selection
+
+After local readiness/profile state is understood, show the environments that this workstation can be prepared to use.
+
+Prefer a multi-select/checkbox-style interaction when the surface supports it. The conceptual shape is:
+
+```text
+SET UP THIS WORKSTATION FOR
+
+[x] Local development — recommended
+[ ] Staging
+[ ] Production
+[ ] <other project-defined environment, e.g. Demo>
+[ ] Other / define another environment
+```
+
+Rules:
+
+- Local development is the recommended/default initial selection.
+- Existing named environments come from the project's current deployment topology, not a hard-coded Staging/Production list.
+- Show each environment's purpose/role compactly when the name alone is ambiguous.
+- Free-form selection remains valid when checkbox UI is unavailable.
+- Selecting an environment means **prepare this workstation for that environment**; it does not deploy the project's real application.
+- Do not force the developer to configure every environment in one session. `/setup` can be rerun later to add another capability.
+
+### Topology source of truth
+
+Prefer project-owned mutable deployment topology:
+
+```text
+DEPLOYMENT_TOPOLOGY.json
+```
+
+Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
+
+`PROJECT_BOOTSTRAP.json` is generation/provenance evidence and should not be casually rewritten merely because a developer adds an environment later.
+
+If an older POC has no `DEPLOYMENT_TOPOLOGY.json` and the developer chooses to add/change a logical environment, first materialize the currently approved deployment topology into the project-owned file, then make the scoped project configuration change there. Preserve the original Bootstrap provenance file.
+
+A topology entry should keep logical identity distinct from purpose and placement. A name such as `demo`, `qa`, or `prod-east` is the command-facing environment identity. Its purpose remains one of the project-supported semantic roles such as development/demo/staging/production.
+
+### Other / define another environment
+
+When the developer chooses **Other**, guide only the material choices needed to create a durable environment definition, normally:
+
+```text
+Name ............ demo
+Purpose ......... demo / staging / production / development
+Placement ....... workstation / remote-target / managed-service / deferred
+Target .......... <when placement requires one>
+Isolation ....... <project/catalog-supported option>
+Exposure ........ <project/catalog-supported option>
+```
+
+Provide recommended choices from the existing project topology/catalog and always allow `Other / specify` or `Not sure — recommend one` where appropriate.
+
+Persist the approved logical environment definition before claiming it is configured. Normalize the command-facing name to the repository-supported safe slug form. Once saved, all normal environment commands use that exact name, for example:
+
+```text
+/deployment-readiness demo
+/deploy demo
+/tear-down demo
+```
+
+Do not create an environment whose required placement/adapter is unsupported; report the concrete `CATALOG GAP` or deferred state instead.
+
+## 6. Prepare selected remote environments
+
+For each selected non-local environment, reuse the project's topology plus the developer's portable target/profile definition and establish this workstation's machine-specific capability as far as supported:
+
+```text
+logical environment
+→ target/profile definition
+→ this-workstation SSH identity/trust when applicable
+→ target access
+→ host/platform prerequisites/readiness
+→ deployment-path proof when supported
+```
+
+Never copy SSH private keys/trust from another workstation. Another workstation's successful readiness is useful project context, not proof that this workstation can deploy.
+
+If host prerequisites cannot yet be prepared automatically, report the exact preparation gap instead of weakening `sudo`, trust, or credential boundaries.
+
+## 7. Prove the deployment path with a disposable Project Forge probe
+
+When the installed Deployment Kit exposes environment proof operations, a selected remote environment should normally be taken through an end-to-end **environment proof deployment** during setup.
+
+The proof is not the POC application. It is a tiny disposable Project Forge-owned probe that should:
+
+```text
+acquire a small stable probe image on this workstation
+→ resolve its exact immutable digest
+→ transfer that exact image using the real workstation-mediated path
+→ deploy under a reserved probe identity
+→ verify runtime/HTTP health
+→ remove the probe
+→ verify cleanup
+```
+
+For the current standard Deployment Kit, use the repository-distributed command when available, conceptually:
+
+```text
+python tools/project-forge-deployment/project-forge-deploy.py environment proof plan \
+  <target> --owner-repo <owner/repo> --environment <name>
+
+python tools/project-forge-deployment/project-forge-deploy.py environment proof run \
+  <target> --owner-repo <owner/repo> --environment <name> --yes
+```
+
+Use the actual installed command/help contract rather than blindly copying examples.
+
+A successful proof demonstrates this workstation can use the real image-transfer/application-runtime/health path. It must not create project data or claim the project's application has been deployed.
+
+Preferred state after proof:
+
+```text
+Environment ........... demo
+Target/access ......... READY
+Host platform ......... READY
+Deployment path ....... PROVEN
+Project application ... NOT YET DEPLOYED
+```
+
+If cleanup fails, report `PROOF PASSED — CLEANUP ACTION NEEDED`; do not claim a clean setup.
+
+### Authorization during setup
+
+For a selected **non-Production** environment, the developer's explicit `/setup` selection plus a clear preview of the disposable proof may cover the bounded proof write. Use the deterministic tool's exact authorization contract and do not add multiple ceremonial prompts.
+
+For any environment whose resolved purpose is **production**, keep one explicit consequential gate before the proof writes to it:
+
+```text
+PRODUCTION ENVIRONMENT PROOF
+
+Project Forge is ready to temporarily deploy a disposable environment probe to <name>,
+verify it, and remove it. No project application or project data will be deployed.
+
+1. Run Production environment proof
+2. Verify access/readiness only
+3. Skip this environment for now
+```
+
+A custom Production name such as `prod-east` remains Production because of its resolved purpose/classification. Never downgrade Production safety based on the literal environment string.
+
+## 8. First real application deployment remains streamlined
+
+Environment proof should intentionally answer environment/mechanics questions once. Later, the first `/deploy <environment>` with real application code should ask only application-specific questions that are still unresolved, such as exact health contract, persistence, exposure/route, or immutable application artifact policy.
+
+Do not repeat already-proven target/access/transport setup unless evidence changed.
+
+Environment proof never authorizes a later real application deployment, and Production proof never authorizes Production application deployment.
+
+## 9. Human workspace acceptance remains meaningful
+
+Machine success is evidence, not human acceptance.
+
+When selected setup work passes, report what is ready and hand off to `/next-step` for remaining human editor/workspace acceptance and work-item navigation.
+
+Preferred completion shape:
+
+```text
+SETUP COMPLETE
+
+Workspace instance .... <machine/platform or local friendly name>
+Workstation tools ...... READY
+Personal profile ....... READY / DEFERRED
+Project dependencies ... READY / DEFERRED
+Local runtime .......... READY / DEFERRED / NOT APPLICABLE
+Workspace checks ....... READY
+
+ENVIRONMENT CAPABILITIES
+Local .................. READY
+Demo ................... PROVEN / READY / NOT CONFIGURED
+Staging ................ PROVEN / READY / NOT CONFIGURED
+Production ............. PROVEN / ACCESS READY / NOT CONFIGURED
+
+Next:
+  /next-step
+```
+
+Do not silently mark editor/agent discovery accepted on the developer's behalf.
+
+## 10. Concurrent workspace rules
+
+Multiple workstations may work on the same project concurrently.
+
+Prefer independent short-lived branches for independent workstreams. If this checkout uses a branch another workspace may also update, inspect upstream/remote divergence before branch-changing, delivery, or history-sensitive actions. A remote branch advancing from another workstation is normal evidence, not corruption.
+
+Stop before force/reset/rebase or silent loss of local work; route reconciliation through the normal Git/work-item flow.
+
+`/setup` itself does not commit, push, merge, switch work-item branches, copy worktree changes between computers, or use stash as cross-workstation storage.
+
+Shared remote environment mutations remain protected by the Deployment Kit's environment/application locking and readiness contracts.
+
+## 11. `status`, `repair`, local, remote, and named-environment options
+
+`/setup status` is read-only. Report current setup/readiness for **this workspace instance** and all project-defined environments without mutating them.
+
+`/setup repair` repairs only missing/safely reproducible state. Preserve valid tools, keys, trust, databases, Docker state, and project files.
+
+`/setup local` targets local workstation convergence.
+
+`/setup remote` presents the guided named-environment selector rather than assuming only Staging/Production.
+
+`/setup <environment>` may directly select one existing project-defined environment (for example `/setup demo`) and run the same readiness/proof flow. It must resolve the name from project topology and never invent or silently fall back to another environment.
+
+When the installed Deployment Kit exposes profile migration and this workstation already has valid target definitions but no personal profile model, prefer the deterministic migration command. Migration may publish only sanitized target definitions and preserve existing keys/trust; it must not deploy applications or delete old credentials automatically.
+
+## 12. Credential boundary
+
+Never ask the developer to paste passwords, PATs, private SSH keys, or other credentials into chat.
+
+When a repository/tool needs a credential, direct the deterministic local tool to prompt in the local terminal using a hidden/secure prompt. Secrets remain workstation-local and must not be committed to the POC repository or portable profile.
+
+## 13. Relationship to other Project Forge commands
+
+- `/setup` — prepare this workstation/workspace instance and selected named environment capabilities.
+- `/progress` — read-only lifecycle/workspace/environment status.
+- `/next-step` — one sensible next action after current evidence is known.
+- `/developer-env-mode` — direct/advanced local-vs-remote operational readiness command.
+- `/start-work <ID>` — implementation authorization after workspace acceptance.
+- `/deployment-readiness <environment>` — readiness for any exact project-defined environment.
+- `/deploy <environment>` — deploy the real application to any exact project-defined environment, with Production classification preserved.
+- `/tear-down <environment>` — destructively clean only the exact named environment after its own authorization gates.
+
+Keep setup focused: one front door, automatic OS detection, project-defined environment names, deterministic tooling underneath, disposable proof where supported, and stronger Production gates only where they materially matter.

package/assets/generated/core/core/skills/start-work/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: start-work
+description: Assess requirement readiness and implementation risk, then guide direct Agent work or native planning for the configured work item.
+argument-hint: "<work-item ID, external key, or concise change>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Start Work
+
+## 1. Resolve the requested work
+
+Read `.github/project-forge-workspace.json` when present.
+
+Resolve only the context needed:
+- authoritative work-item source,
+- parent/grouping context when actually available,
+- optional Product/Feature/Enabler briefs according to configured authority,
+- local detailed requirements when permitted/present,
+- relevant decisions/ADRs/architecture/standards,
+- current code/tests and branch/diff when relevant.
+
+Do not require local briefs when the repository uses Jira/Issues. Do not invent external content.
+
+## 2. Check requirement readiness before planning
+
+Assess:
+- outcome clarity,
+- acceptance criteria/validation expectations,
+- material domain/engineering rules,
+- dependencies/cross-work-item context,
+- unresolved human decisions,
+- requirement authority/status.
+
+Ask:
+
+```text
+Does detailed precision matter?
+Does the authoritative source contain enough detail?
+If local requirements exist, are they DRAFT or APPROVED?
+Are material decisions unresolved?
+```
+
+If detailed precision is warranted but incomplete, recommend `/refine-requirements`, `/grill-me`, or `/grill-with-docs` rather than silently inventing behavior.
+
+If local requirements are DRAFT and carry material behavior, human approval is the gate before substantive planning/implementation.
+
+If requirements are already sufficient/approved under the configured model, do not force another refinement cycle.
+
+### CI/policy evidence is not a start-work gate
+
+When requirements say CI/checks must pass before a later merge, release, or deployment action, use repository-configured workflows/checks plus observable repository policy/mergeability as the planning evidence available now.
+
+Do not interpret words such as `required CI` or `required checks` as a mandate to discover GitHub branch-protection/ruleset admin settings before implementation can begin. Those settings may provide additional evidence later when they are observable, but inability to read them is not by itself a blocker.
+
+Do not ask the human to open GitHub Settings and transcribe required-check names merely to proceed with `/start-work`. Stop and ask only when actual evidence conflicts or missing policy information creates a concrete unresolved decision that materially affects implementation or the later consequential action.
+
+## 3. Classify risk
+
+### LIGHT
+
+Tiny, obvious, low-risk; no meaningful schema/security/concurrency/deployment/major-UX implications.
+
+```text
+Agent
+→ relevant checks
+→ human meaningful-diff review
+```
+
+No formal plan or detailed requirements are required.
+
+### STANDARD
+
+Meaningful multi-file work.
+
+```text
+requirements ready as needed
+→ native plan
+→ HUMAN PLAN APPROVAL
+→ short-lived work branch setup
+→ Agent implementation
+→ checks
+→ Reviewer
+→ human meaningful-diff acceptance
+```
+
+### ELEVATED
+
+Use for:
+- schema/data-loss risk,
+- authentication/security,
+- concurrency/transactions,
+- release/deployment/recovery,
+- significant architecture,
+- broad cross-layer changes,
+- hard-to-reverse decisions.
+
+```text
+detailed approved requirements / ADR as needed
+→ native plan
+→ Reviewer challenges plan
+→ HUMAN PLAN APPROVAL
+→ short-lived work branch setup
+→ implementation in small slices
+→ stronger verification
+→ Reviewer
+→ human acceptance
+```
+
+Explain why the level was chosen.
+
+## 4. Optional learning checkpoint
+
+For STANDARD/ELEVATED work, once requirements are ready, coaching may be offered but is never required:
+
+```text
+1. Continue without coaching — recommended default
+2. /coach for a short pre-build concept review
+3. /grill-me for challenge rather than teaching
+4. Stop
+```
+
+For LIGHT work, do not interrupt with coaching unless requested.
+
+## 5. Planning rules
+
+For STANDARD/ELEVATED work:
+- use the editor's current native planning capability,
+- plan approach, affected areas, key decisions, risks, and verification,
+- require human plan approval before implementation,
+- do not auto-launch subagents,
+- do not create mandatory `spec.md` or `tasks.md`,
+- save a durable plan only when it is useful across sessions or for genuinely complex/risky work.
+
+## 6. Working branch setup
+
+Once implementation is authorized to begin, establish the repository-appropriate short-lived work branch as routine setup before substantive edits.
+
+Do not ask a separate branch-creation permission when all of the following are true:
+- the current branch is the default/integration branch and repository policy expects short-lived work branches,
+- the work-item boundary is clear,
+- the target branch name is unambiguous under repository convention or the Project Forge fallback below,
+- creating/switching branches does not require history rewriting or discarding work.
+
+Branch naming order:
+1. repository/team convention when defined,
+2. an already-existing branch clearly tied to the work item,
+3. Project Forge fallback: `<lowercase-work-item-id>-<concise-slug>` for ID-backed work, or `work/<concise-slug>` for a concise ad hoc change.
+
+Examples of the fallback shape are conceptual only; never invent a consumer-specific work-item ID in Core documentation or behavior.
+
+If scoped uncommitted changes already exist on the default branch and clearly belong to this work item, preserve them while creating/switching to the short-lived branch when Git can do so safely. Verify that the worktree diff is unchanged after the branch switch.
+
+Stop and ask only when branch policy/naming is materially ambiguous, the intended branch already exists with divergent work, unrelated changes are present, or the operation would require stash/reset/rebase/force/history rewriting.
+
+For LIGHT work, branch setup is part of the human-selected implementation action. For STANDARD/ELEVATED work, it is part of the approved implementation start after plan approval. Merely inspecting `/start-work` does not authorize implementation before its required gate.
+
+## 7. Deployment enabler
+
+When a work item owns release/deployment engineering or environment enablement, classify it ELEVATED when the change materially affects deployment/recovery/security behavior.
+
+Environment readiness may begin early with the normal state-driven interface:
+
+```text
+/deployment-readiness <environment>
+```
+
+It begins with existing local/repository configuration, shows simple known machine facts for confirmation, and continues only as far as current engineering/evidence safely allows. It does not authorize application deployment.
+
+After implementation review/local acceptance, use `/deliver`. After `/deliver` reports the merge, default-branch CI, and applicable repository-policy evidence satisfied, return to the same state-driven readiness command for the selected environment:
+
+```text
+/deployment-readiness <environment>
+```
+
+The workflow re-discovers state and continues from the furthest safe point; do not require the human to switch from a discovery mode to an enable mode.
+
+Production remains a role with stronger policy and deployment authorization; it does not use a separate readiness workflow.
+
+## 8. Guided ending
+
+Return:
+- CURRENT STATE,
+- risk level and why,
+- requirement readiness,
+- branch state / expected short-lived branch when implementation is about to begin,
+- RECOMMENDED NEXT STEP,
+- a small numbered OPTIONS menu with action labels.
+
+Do not skip an unresolved requirement/plan gate merely because implementation is technically possible. Once implementation is selected/approved, do not insert a separate ceremonial branch-creation gate when the branch setup is safe and deterministic.