@mriekki/project-forge 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,90 @@
+---
+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. 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 choice such as:
+
+```text
+1. Continue grilling only [READ ONLY]
+2. Reconcile resolved decisions during this session [MODIFIES DOCS]
+3. Stop [NO ACTION]
+```
+
+After option 2 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`.

package/assets/generated/core/core/skills/learning-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: learning-review
+description: Optional structured post-build understanding check using actual implementation, tests, decisions, and work-item context.
+argument-hint: "<work-item ID, external key, or topic>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Learning Review
+
+Default to post-build learning from real evidence.
+
+`/learning-review` is primarily assessment. For an instructional changed-file walkthrough first, use `/code-walkthrough`.
+
+## 1. Context
+
+Read only relevant:
+- work-item/requirements context,
+- changed code/diff,
+- tests and observed results,
+- important decisions/architecture.
+
+Identify 3–6 concepts the developer should understand.
+
+## 2. Continuous cadence
+
+Ask one question at a time:
+
+```text
+question
+→ human answer
+→ critique accuracy/depth/credibility
+→ teach missing concept when useful
+→ next question
+```
+
+Do not ask whether to continue after every answer.
+
+Assess:
+- architecture/request/data flow,
+- technical decisions and alternatives,
+- debugging/testing,
+- failure modes/tradeoffs,
+- interview explanation.
+
+Do not edit production code while in learning-review mode.
+
+## 3. Relationship to code walkthrough
+
+Use `/code-walkthrough` when the primary need is:
+
+```text
+AI explains the actual implementation
+→ developer explores changed files
+→ developer builds a mental model
+```
+
+Use `/learning-review` when the primary need is:
+
+```text
+AI asks
+→ developer explains
+→ AI critiques
+→ gaps become visible
+```
+
+A walkthrough may naturally hand off to a learning review, but neither is required for engineering completion or delivery.
+
+## 4. Credibility
+
+Explicitly distinguish:
+- what the developer actually implemented/used,
+- what AI generated but the developer reviewed/understands,
+- what was studied/practiced,
+- what remains a gap.
+
+Do not manufacture professional experience.
+
+## 5. Completion
+
+Stop when the human stops/switches workflow, the planned check is complete, or no material learning gaps remain for this session.
+
+Summarize:
+- understood well,
+- needs reinforcement,
+- optional next target.
+
+Then offer a small menu such as continue, optional learning notes/progress, return to engineering workflow, or stop.
+
+`/learning-review` is optional and never blocks engineering completion/delivery.

package/assets/generated/core/core/skills/next-step/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: next-step
+description: Read-only orientation over setup, work-item, Git, review, PR, PR CI, merge, post-merge default-branch CI, deployment readiness, deployment handoff state, and optional documentation/learning surfaces.
+argument-hint: "[optional work-item ID or external key]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Next Step
+
+Purpose: answer `Where am I, and what is the sensible next action?`
+
+Invocation is read-only. `/progress` gives the broader milestone/status view; `/next-step` recommends one useful action from current evidence.
+
+## 1. Resolve minimum context
+
+Before assuming implementation has started, inspect enough workspace evidence to determine whether this checkout has completed local setup and human workspace acceptance. Useful setup evidence may include `DEV_ENVIRONMENT.json`, generated setup/doctor outputs, workstation-local developer-mode evidence, and the current session's acceptance state.
+
+Read `.github/project-forge-workspace.json` when present and use the optional work-item key or infer from current branch/session context.
+
+Inspect only what is needed. Never invent setup/Jira/Issue/PR/CI/review/merge/readiness/deployment state.
+
+Local Git examples:
+
+```text
+git branch --show-current
+git status --short --branch
+git diff --stat
+git diff --cached --stat
+git log -1 --oneline
+```
+
+When GitHub CLI is available/authenticated:
+
+```text
+gh pr status
+gh pr view
+gh pr checks
+```
+
+When post-merge CI matters, inspect the configured default branch/workflow rather than assuming it is named `main`.
+
+## 2. Setup comes before implementation
+
+When the repository is generated but this workstation is not ready, recommend:
+
+```text
+/setup
+```
+
+Do not make the developer manually sequence tool installation, dependency restore, local mode convergence, doctor, or remote-target setup when `/setup` can route those concerns.
+
+Typical pre-work states:
+
+```text
+LOCAL_SETUP_PENDING
+LOCAL_SETUP_BLOCKED
+WORKSPACE_ACCEPTANCE_PENDING
+READY_FOR_FIRST_WORK_ITEM
+```
+
+Rules:
+
+- local readiness is the first success target;
+- intentionally unconfigured/deferred Staging or Production does not block local coding;
+- a deferred application scaffold may still have a ready workspace;
+- machine checks do not accept the editor/workspace experience on the human's behalf.
+
+When deterministic setup passes but human workspace acceptance is still needed, recommend the smallest meaningful acceptance check using `docs/process/SETUP_ACCEPTANCE_CHECKLIST.md` and current editor/agent evidence. Do not rerun setup without evidence it is needed.
+
+When the workspace is accepted and the first approved work item is clear, recommend `/start-work <ID>`.
+
+If the developer wants the broader status instead of one action, offer `/progress` as a read-only option.
+
+## 3. Engineering/delivery states
+
+Examples:
+
+```text
+IMPLEMENTING
+LOCAL_REVIEW_PENDING
+REVIEW_CHANGES_REQUIRED
+REVIEW_READY
+HUMAN_LOCAL_ACCEPTANCE_PENDING
+DELIVERY_READY
+PUSHED_NO_PR
+PR_CI_PENDING
+PR_CI_FAILED
+PR_CI_GREEN
+MERGE_READY
+MERGED_DEFAULT_BRANCH_CI_PENDING
+MERGED_DEFAULT_BRANCH_CI_FAILED
+DELIVERY_COMPLETE
+ENVIRONMENT_READINESS_PENDING
+ENVIRONMENT_READY_TO_DEPLOY
+DEPLOYMENT_VALIDATION_PENDING
+```
+
+Use only states supported by observed evidence.
+
+Do not add a separate final-PR-acceptance state when the PR still exactly matches the already accepted local implementation. In that normal case, `/deliver` combines final acceptance and merge into the single `MERGE_READY` decision. If PR evidence changed materially, describe the required final PR review explicitly before returning to `MERGE_READY`.
+
+Do not add learning- or documentation-only states. Optional coaching, labs, and project documentation do not change engineering delivery state unless the approved work item explicitly makes documentation acceptance evidence.
+
+## 4. Output
+
+```text
+CURRENT STATE
+<evidence-backed summary>
+
+RECOMMENDED NEXT STEP
+<one action and why>
+
+OPTIONS
+1. ... [READ ONLY]
+2. ... [MODIFIES FILES]
+3. ... [GIT + GITHUB WRITE]
+4. Stop [NO ACTION]
+```
+
+Only show relevant options. `/next-step` orients; it does not become another workflow database.
+
+For an unprepared generated workspace, a good result is simply:
+
+```text
+CURRENT STATE
+Local setup has not been completed on this computer.
+
+RECOMMENDED NEXT STEP
+/setup
+
+OPTIONS
+1. /progress [READ ONLY]
+2. Stop [NO ACTION]
+```
+
+## 5. Optional documentation and learning choices
+
+When implementation is stable enough to understand or document, `/next-step` may offer these choices without making them gates:
+
+```text
+/docs [open|check|build]
+/code-walkthrough <scope>
+/learning-review <scope>
+/coach <topic>
+/db-lab [changes <work-item>]
+/system-lab [changes <work-item>]
+```
+
+Prefer `/docs` for the coherent project briefing/document map, `/code-walkthrough` for implementation flow, `/db-lab` for concrete schema/query/index/ORM evidence, and `/system-lab` for architecture/runtime/failure/scale evidence.
+
+Safe generated projections may be prepared automatically. Do not silently rewrite project-owned prose, accept an ADR, or make learning mandatory before `/deliver` unless the approved work item explicitly requires it.
+
+## 6. Delivery handoff
+
+When all are ready:
+
+```text
+implementation complete
+local verification satisfactory
+Reviewer READY
+human meaningful-diff approval complete
+```
+
+recommend `/deliver` rather than separate branch/commit/push/create-PR confirmations.
+
+`/deliver` owns the compound delivery action:
+
+```text
+short-lived branch setup/recovery when needed
+→ selective stage
+→ verify staged diff
+→ commit
+→ push
+→ create/update PR
+→ PR CI
+→ one Merge and finalize delivery decision
+→ merge
+→ post-merge default-branch CI
+→ safe delivered-branch finalization
+```
+
+Because `/deliver` is manually invoked, do not insert another permission menu merely to begin those routine mechanics. It will stop itself for changed evidence, ambiguity/risk, CI failure requiring code changes, or the merge/finalize decision.
+
+If PR CI failed, recommend inspect/diagnose/targeted fix. Do not silently change code. If PR CI is green and evidence still matches the accepted implementation, return to `/deliver` for the single merge/finalize gate. Never merge from `/next-step` merely because CI is green.
+
+After merge, return to `/deliver` while required default-branch CI/finalization is incomplete; otherwise report delivery complete and only optional relevant documentation/learning follow-ups.
+
+## 7. Deployment handoff
+
+For release/deployment engineering after engineering delivery is complete, recommend the selected environment's state-driven readiness workflow:
+
+```text
+/deployment-readiness <environment>
+```
+
+Use the same command whether the environment still needs initial discovery, prerequisite setup, repair, or final pre-deploy verification. Readiness re-discovers current state and resumes automatically; do not tell the human to choose discovery/enable/resume modes.
+
+When evidence shows a configured named environment is ready to deploy, recommend:
+
+```text
+/deploy <environment>
+```
+
+`ENVIRONMENT_READY_TO_DEPLOY` means pre-deploy prerequisites are satisfied. It does not require live application health, smoke, route resolution, or release-specific rollback evidence that can only be established by deploying the selected artifact.
+
+After `/deploy`, use repository/tool evidence to distinguish a successfully validated deployment from `DEPLOYMENT_VALIDATION_PENDING` or a deployment failure.
+
+For a read-only overview across configured environments recommend:
+
+```text
+/deployment-readiness status
+```
+
+Do not infer readiness of one environment from another. Production is never an implicit/default environment, and `/next-step` never authorizes a remote or production deployment merely by recommending `/deploy`.
+
+## 8. Keep it focused
+
+Do not auto-run Reviewer, auto-run learning activities, auto-merge, auto-deploy, pin/select a model, or maintain duplicate workflow state outside Git/GitHub and the configured work-item/readiness authority.
+
+Generating a disposable read-only documentation or learning workbench is not the same as performing a learning activity, approving documentation prose, or proving understanding.

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

@@ -0,0 +1,207 @@
+---
+name: progress
+description: "Read-only developer-facing progress view across POC creation, this workspace instance, work-item/delivery state, and exact project-defined environment capabilities."
+argument-hint: "[optional work-item ID or environment]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Progress
+
+Purpose: answer `What is complete, what is happening now, and who needs to act?`
+
+Invocation is read-only. `/progress` is a navigation/status surface, not a second workflow database or central workstation registry.
+
+## 1. Reconstruct progress from evidence
+
+Inspect only the evidence needed for the current lifecycle position. Useful sources include:
+
+- `PROJECT_BOOTSTRAP.json`, generated baselines, and repository history for project creation/provenance;
+- `DEPLOYMENT_TOPOLOGY.json` as preferred project-owned mutable environment topology when present;
+- `DEV_ENVIRONMENT.json`, generated setup scripts, workstation-local setup/developer-mode evidence, and safe setup checks for local readiness;
+- observed OS/platform and machine-local evidence for **this workspace instance**;
+- current Git branch/status/upstream and safe remote-tracking evidence;
+- work-item docs, Reviewer evidence, PR/CI state, and default-branch evidence;
+- environment proof/readiness/deployment evidence for exact project-defined environments.
+
+If `DEPLOYMENT_TOPOLOGY.json` does not exist, use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
+
+Never invent completion because a prior step normally happens. Prefer `UNKNOWN`/`NOT EVIDENCED` over false green state.
+
+Do not mutate setup, Git, GitHub, target, deployment, or project state.
+
+## 2. Use a small status vocabulary
+
+```text
+✓ COMPLETE / READY
+● IN PROGRESS
+○ NOT STARTED
+! ACTION NEEDED
+✕ BLOCKED
+– DEFERRED / NOT APPLICABLE
+? NOT EVIDENCED
+```
+
+Do not use percentage-complete estimates.
+
+## 3. Distinguish project state from this workspace instance
+
+A **workspace instance** is one checkout of one Project Forge project on one developer workstation. Multiple instances may be active at the same time.
+
+When useful, report:
+
+```text
+THIS WORKSPACE
+
+Platform ............. Windows / macOS
+Local setup .......... READY / NOT CONFIGURED / BLOCKED
+Branch ................ <branch>
+Upstream .............. <remote branch or NONE>
+Remote sync ........... UP TO DATE / AHEAD / BEHIND / DIVERGED / NOT EVIDENCED
+Personal profile ...... READY / DEFERRED / BLOCKED
+```
+
+Do not imply another workstation is offline/idle/authoritative unless concrete evidence says so. Machine-local databases, Docker state, credentials, SSH private keys, and host trust are not project-shared state.
+
+If another workspace advanced the same remote branch, report that as normal coordination evidence and recommend fetch/reconciliation before history-sensitive work. Never rebase/reset/force/stash/merge from `/progress`.
+
+## 4. Show meaningful lifecycle milestones
+
+Prefer milestones such as:
+
+```text
+Project creation
+This workspace setup
+Workspace acceptance
+Current work item
+Engineering delivery
+Environment capabilities
+```
+
+Do not expose Bootstrap/package/control-plane plumbing unless a failure there is the actionable blocker.
+
+## 5. Always identify ownership of the next action
+
+Distinguish:
+
+```text
+Owner: Project Forge
+Action from developer: None
+```
+
+from:
+
+```text
+Owner: Developer
+Action: <one concrete action>
+```
+
+Never claim asynchronous/background work unless an actual current operation exists.
+
+## 6. Local setup/readiness
+
+Before first setup on this computer:
+
+```text
+PROJECT STATUS
+
+✓ Project creation
+○ This workspace setup
+○ Workspace acceptance
+○ First work item
+
+THIS WORKSPACE
+Platform ............. macOS
+Local setup .......... NOT CONFIGURED
+
+Next:
+  /setup
+```
+
+After machine checks pass but before human acceptance, show setup ready and workspace acceptance as the developer action.
+
+Do not treat deferred application scaffolding or optional remote environments as failed local setup.
+
+## 7. Engineering/delivery progress
+
+When implementation has begun, summarize the current work item and only delivery states supported by evidence.
+
+Different workstations may work on independent work items/branches concurrently. Same-branch remote advancement is coordination evidence, not corruption.
+
+If work is delivery-complete and deployment is the next useful action, identify the exact project-defined environment; do not assume Staging unless topology/policy says so.
+
+## 8. Environment capabilities are topology-driven
+
+Enumerate exact names from current project topology rather than a fixed Local/Staging/Production list.
+
+A useful shape is:
+
+```text
+ENVIRONMENT CAPABILITIES — THIS WORKSTATION
+
+Local ............ READY
+Demo ............. PROVEN
+QA ............... NOT CONFIGURED
+prod-east ........ ACCESS READY
+```
+
+For each named environment distinguish evidence when useful:
+
+```text
+purpose/classification
+placement/binding
+target access from this workstation
+environment proof deployment state
+real project application deployment state
+```
+
+Example:
+
+```text
+Demo
+  Purpose .............. demo
+  Target access ........ READY
+  Deployment path ...... PROVEN
+  Project application .. NOT YET DEPLOYED
+```
+
+A setup-time disposable proof means the environment mechanics were proven from this workstation; it does not mean the real project application is deployed.
+
+A custom name such as `prod-east` with purpose `production` must be presented as Production-class and retain stronger later gates.
+
+`Production-class NOT CONFIGURED` does not make local/non-Production work incomplete.
+
+Shared remote environments may be reachable from multiple workspace instances. Access/trust proof is per workstation; remote runtime/environment state is shared. Respect app/environment deployment locking when reporting concurrent mutations.
+
+## 9. Handoff to `/next-step`
+
+`/progress` answers where the developer is. `/next-step` recommends one sensible action.
+
+Examples:
+
+```text
+Next:
+  /setup
+```
+
+```text
+Next:
+  /start-work EN01
+```
+
+```text
+Next:
+  /setup demo
+```
+
+```text
+Next:
+  /deployment-readiness demo
+```
+
+```text
+Next:
+  /deploy demo
+```
+
+Do not perform that action from `/progress`.