@mriekki/project-forge 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Project Forge
+
+**Build real software. Learn the engineering behind it.**
+
+Project Forge is an AI-guided software development and learning platform for building your own projects from idea through definition, implementation, testing, deployment, and structured learning.
+
+The Builder brings the idea and makes the material decisions. Project Forge supplies a repeatable engineering path, deterministic project generation, AI-assisted implementation and review, environment setup and deployment guidance, and optional learning and coaching.
+
+## What it feels like
+
+Start with an idea:
+
+```text
+New Project: I want to build a hiking trail tracker.
+```
+
+Project Forge guides the Builder through:
+
+```text
+idea
+→ project discovery
+→ V1 scope and non-goals
+→ technology and testing choices
+→ project definition
+→ private GitHub project creation
+→ deterministic workspace generation
+→ local setup
+→ small work items
+→ implementation + tests
+→ meaningful review
+→ delivery / pull request / CI
+→ optional deployment
+→ optional code walkthrough, learning review, and coaching
+```
+
+## What Project Forge is for
+
+Project Forge supports personal software projects, learning projects, technology explorations, automation, APIs, web/mobile/desktop applications, embedded projects, AI/LLM projects, testing projects, and other supported software shapes.
+
+Projects can grow beyond an initial experiment. They can have persistent data, CI, multiple workstations, named environments such as Demo, Staging, and Production, deployment, and ongoing work items.
+
+## Human control stays meaningful
+
+Project Forge automates routine mechanics but keeps important decisions with the Builder:
+
+- material requirements and scope;
+- substantive implementation plans when warranted;
+- meaningful code and diff acceptance;
+- pull-request merge and finalization;
+- release publication;
+- Production deployment or destructive Production actions.
+
+Learning is optional and never blocks delivery.
+
+## Your projects are yours
+
+Each Builder owns their own project repositories and development credentials.
+
+Project Forge authorization does not grant access to another developer's private projects. Builders do not need access to Project Forge's private platform implementation repositories.
+
+Private platform components provide the engineering workflow, project-generation, deployment, and orchestration capabilities behind the public Project Forge experience. Builders interact with Project Forge through the public onboarding flow, their own generated project repositories, the public ChatGPT contract, and the published `@mriekki/project-forge` package.
+
+## New Builder onboarding
+
+Read the product overview and onboarding journey in [`WELCOME.md`](WELCOME.md).
+
+An invited Builder normally does only this:
+
+```text
+open personal invitation
+→ install/approve Project Forge Builder
+→ accept invitation
+→ automatic readiness verification
+→ configure one ChatGPT coding Project
+→ New Project: <idea>
+```
+
+**Project Forge Builder** is the GitHub App used for Project Forge authorization and project orchestration.
+
+One-time ChatGPT setup is documented in [`chatgpt/SETUP.md`](chatgpt/SETUP.md).
+
+## Working in a generated project
+
+A generated project is self-contained for normal development. The normal workstation flow is:
+
+```text
+clone repository
+→ open generated VS Code workspace
+→ /setup
+→ /progress or /next-step
+→ /start-work <ID>
+```
+
+Project Forge supports independent workspace instances on multiple developer computers. Git/GitHub is the shared source boundary; local databases, credentials, SSH keys/trust, Docker state, and readiness stay workstation-local.
+
+## Public ChatGPT contract
+
+Project Forge's public ChatGPT bootstrap entrypoint is [`chatgpt/START_HERE.md`](chatgpt/START_HERE.md).
+
+The stable descriptor at `chatgpt/current.json` resolves an immutable Project Forge contract snapshot for each conversation/session. New contract versions are published as new snapshot directories so an already-resolved session keeps a stable contract.
+
+## Public engineering distribution
+
+`@mriekki/project-forge` is the public distribution for Project Forge engineering assets used by generated projects.
+
+Project Forge assembles that package from approved private platform components using exact pinned source commits and deterministic distribution descriptors. Published packages are self-contained; Builders do not need access to the private implementation repositories to install or update managed assets.
+
+Install:
+
+```powershell
+npx @mriekki/project-forge install
+```
+
+Update to the newest published package:
+
+```powershell
+npx @mriekki/project-forge@latest update
+```
+
+Inspect and verify:
+
+```powershell
+npx @mriekki/project-forge@latest status
+npx @mriekki/project-forge@latest check
+```
+
+Managed updates verify baselines and refuse unsafe drift or conflicts before modifying Project Forge-managed files.
+
+## Maintainer release process
+
+Project Forge maintainers use a gated release workflow that resolves accepted component commits, verifies the assembled package, creates the package pull request, verifies CI, and stops at the explicit publication gate.
+
+Publication uses npm Trusted Publishing (OIDC), reconstructs the exact package from pinned sources, verifies registry identity and integrity, and smoke-tests the public package from a neutral directory.
+
+See [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) for the technical release contract.

package/assets/components.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "package": "@mriekki/project-forge",
+  "version": "1.0.0",
+  "defaultProfile": "greenfield-project",
+  "profiles": {
+    "greenfield-project": {
+      "components": [
+        "core",
+        "deployment"
+      ]
+    }
+  },
+  "components": {
+    "core": {
+      "repository": "mriekki/project-forge-core",
+      "commit": "78065f0ab59506e8cc703f6bf7dfd31fc71f313f",
+      "version": "2.0.0",
+      "distribution": "greenfield-workspace",
+      "descriptor": "assets/core/distribution.json",
+      "sourceRoot": "assets/generated/core",
+      "canonicalDescriptor": "distributions/greenfield-workspace.json"
+    },
+    "deployment": {
+      "repository": "mriekki/project-forge-deployment-kit",
+      "commit": "54fcc256c525ea8762568043c3900f4d2d36c816",
+      "distribution": "greenfield-project",
+      "descriptor": "assets/deployment/distribution.json",
+      "sourceRoot": "assets/generated/deployment",
+      "canonicalDescriptor": "distributions/greenfield-project.json"
+    }
+  }
+}

package/assets/core/distribution.json

@@ -0,0 +1,66 @@
+{
+  "name": "greenfield-workspace",
+  "profileSource": "profiles/greenfield/project-forge-workspace.json",
+  "profileDestination": ".github/project-forge-workspace.json",
+  "mappings": [
+    {"source":"core/agents/reviewer.agent.md","destination":".github/agents/reviewer.agent.md"},
+    {"source":"core/agents/coach.agent.md","destination":".github/agents/coach.agent.md"},
+    {"source":"core/instructions/project-forge-workflow.instructions.md","destination":".github/instructions/project-forge-workflow.instructions.md"},
+    {"source":"core/instructions/project-forge-docs.instructions.md","destination":".github/instructions/project-forge-docs.instructions.md"},
+    {"source":"core/skills/define-feature/SKILL.md","destination":".github/skills/define-feature/SKILL.md"},
+    {"source":"core/skills/grill-me/SKILL.md","destination":".github/skills/grill-me/SKILL.md"},
+    {"source":"core/skills/grill-with-docs/SKILL.md","destination":".github/skills/grill-with-docs/SKILL.md"},
+    {"source":"core/skills/refine-requirements/SKILL.md","destination":".github/skills/refine-requirements/SKILL.md"},
+    {"source":"core/skills/start-work/SKILL.md","destination":".github/skills/start-work/SKILL.md"},
+    {"source":"core/skills/setup/SKILL.md","destination":".github/skills/setup/SKILL.md"},
+    {"source":"core/skills/progress/SKILL.md","destination":".github/skills/progress/SKILL.md"},
+    {"source":"core/skills/next-step/SKILL.md","destination":".github/skills/next-step/SKILL.md"},
+    {"source":"core/skills/deliver/SKILL.md","destination":".github/skills/deliver/SKILL.md"},
+    {"source":"core/skills/cleanup-branches/SKILL.md","destination":".github/skills/cleanup-branches/SKILL.md"},
+    {"source":"core/skills/pull-latest/SKILL.md","destination":".github/skills/pull-latest/SKILL.md"},
+    {"source":"core/skills/project-forge-update/SKILL.md","destination":".github/skills/project-forge-update/SKILL.md"},
+    {"source":"core/skills/core-sync/SKILL.md","destination":".github/skills/core-sync/SKILL.md"},
+    {"source":"core/skills/upstream-fix/SKILL.md","destination":".github/skills/upstream-fix/SKILL.md"},
+    {"source":"core/skills/wait-what/SKILL.md","destination":".github/skills/wait-what/SKILL.md"},
+    {"source":"core/skills/developer-env-mode/SKILL.md","destination":".github/skills/developer-env-mode/SKILL.md"},
+    {"source":"core/skills/deployment-readiness/SKILL.md","destination":".github/skills/deployment-readiness/SKILL.md"},
+    {"source":"core/skills/deploy/SKILL.md","destination":".github/skills/deploy/SKILL.md"},
+    {"source":"core/skills/tear-down/SKILL.md","destination":".github/skills/tear-down/SKILL.md"},
+    {"source":"core/skills/coach/SKILL.md","destination":".github/skills/coach/SKILL.md"},
+    {"source":"core/skills/db-lab/SKILL.md","destination":".github/skills/db-lab/SKILL.md"},
+    {"source":"core/skills/system-lab/SKILL.md","destination":".github/skills/system-lab/SKILL.md"},
+    {"source":"core/skills/docs/SKILL.md","destination":".github/skills/docs/SKILL.md"},
+    {"source":"core/skills/code-walkthrough/SKILL.md","destination":".github/skills/code-walkthrough/SKILL.md"},
+    {"source":"core/skills/learning-review/SKILL.md","destination":".github/skills/learning-review/SKILL.md"},
+    {"source":"core/process/WORK_ITEM_MODEL.md","destination":"docs/process/WORK_ITEM_MODEL.md"},
+    {"source":"core/process/PR_WORKFLOW.md","destination":"docs/process/PR_WORKFLOW.md"},
+    {"source":"core/process/DEPLOYMENT_ENABLEMENT.md","destination":"docs/process/DEPLOYMENT_ENABLEMENT.md"},
+    {"source":"core/process/HUMAN_GATES.md","destination":"docs/process/HUMAN_IN_LOOP_GATES.md"},
+    {"source":"core/process/GUIDED_NEXT_STEPS.md","destination":"docs/process/GUIDED_NEXT_STEPS.md"},
+    {"source":"core/process/INTERACTIVE_SESSION_GUIDE.md","destination":"docs/process/INTERACTIVE_SESSION_GUIDE.md"},
+    {"source":"core/process/COACHING_GUIDE.md","destination":"docs/process/COACHING_GUIDE.md"},
+    {"source":"core/process/DATABASE_LEARNING_WORKBENCH.md","destination":"docs/process/DATABASE_LEARNING_WORKBENCH.md"},
+    {"source":"core/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md","destination":"docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md"},
+    {"source":"core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md","destination":"docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md"},
+    {"source":"core/process/PROJECT_FORGE_ENGINEERING_GUIDE.md","destination":"docs/project-forge/PROJECT_FORGE_ENGINEERING_GUIDE.md"},
+    {"source":"core/process/SETUP_ACCEPTANCE_CHECKLIST.md","destination":"docs/process/SETUP_ACCEPTANCE_CHECKLIST.md"},
+    {"source":"core/templates/PULL_REQUEST_TEMPLATE.md","destination":".github/PULL_REQUEST_TEMPLATE.md"},
+    {"source":"core/templates/PRODUCT_BRIEF_TEMPLATE.md","destination":"docs/templates/PRODUCT_BRIEF_TEMPLATE.md"},
+    {"source":"core/templates/FEATURE_BRIEF_TEMPLATE.md","destination":"docs/templates/FEATURE_BRIEF_TEMPLATE.md"},
+    {"source":"core/templates/REQUIREMENTS_TEMPLATE.md","destination":"docs/templates/REQUIREMENTS_TEMPLATE.md"},
+    {"source":"core/templates/ADR_TEMPLATE.md","destination":"docs/templates/ADR_TEMPLATE.md"},
+    {"source":"core/learning/ENGINEERING_LEARNING_WORKBOOK.md","destination":"learning/ENGINEERING_LEARNING_WORKBOOK.md"},
+    {"source":"core/learning/LEARNING_MAP.md","destination":"learning/LEARNING_MAP.md"},
+    {"source":"core/learning/LEARNING_PROGRESS.md","destination":"learning/LEARNING_PROGRESS.md"},
+    {"source":"core/learning/CODING_DRILLS.md","destination":"learning/CODING_DRILLS.md"},
+    {"source":"core/learning/SQL_DRILLS.md","destination":"learning/SQL_DRILLS.md"},
+    {"source":"core/learning/SYSTEM_DESIGN_DRILLS.md","destination":"learning/SYSTEM_DESIGN_DRILLS.md"},
+    {"source":"core/learning/DIAGRAM_GUIDE.md","destination":"learning/DIAGRAM_GUIDE.md"},
+    {"source":"core/learning/RESOURCE_CATALOG.md","destination":"learning/RESOURCE_CATALOG.md"},
+    {"source":"tools/db_lab/sqlite_workbench.py","destination":"tools/project-forge-db-lab/sqlite-workbench.py"},
+    {"source":"tools/system_lab/system_workbench.py","destination":"tools/project-forge-system-lab/system-workbench.py"},
+    {"source":"tools/docs_site/docs_site.py","destination":"tools/project-forge-docs/docs-site.py"},
+    {"source":"tools/package/check_baseline.py","destination":"tools/project-forge-core/check-core-baseline.py"},
+    {"source":"tools/package/check_upstream.py","destination":"tools/project-forge-core/check-core-upstream.py"}
+  ]
+}

package/assets/deployment/distribution.json

@@ -0,0 +1,54 @@
+{
+  "name": "greenfield-project",
+  "schemaVersion": 1,
+  "description": "Reusable deployment tooling for generated Project Forge projects.",
+  "mappings": [
+    {"source": "distribution/project-forge-deploy.py", "destination": "tools/project-forge-deployment/project-forge-deploy.py"},
+    {"source": "src/project_forge_deployment/__init__.py", "destination": "tools/project-forge-deployment/project_forge_deployment/__init__.py"},
+    {"source": "src/project_forge_deployment/__main__.py", "destination": "tools/project-forge-deployment/project_forge_deployment/__main__.py"},
+    {"source": "src/project_forge_deployment/app_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/app_cli.py"},
+    {"source": "src/project_forge_deployment/app_runtime.py", "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime.py"},
+    {"source": "src/project_forge_deployment/app_runtime_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime_remote.py"},
+    {"source": "src/project_forge_deployment/app_runtime_workstation.py", "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime_workstation.py"},
+    {"source": "src/project_forge_deployment/box_platform.py", "destination": "tools/project-forge-deployment/project_forge_deployment/box_platform.py"},
+    {"source": "src/project_forge_deployment/box_platform_assets.py", "destination": "tools/project-forge-deployment/project_forge_deployment/box_platform_assets.py"},
+    {"source": "src/project_forge_deployment/box_platform_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/box_platform_remote.py"},
+    {"source": "src/project_forge_deployment/cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/cli.py"},
+    {"source": "src/project_forge_deployment/doctor.py", "destination": "tools/project-forge-deployment/project_forge_deployment/doctor.py"},
+    {"source": "src/project_forge_deployment/entrypoint.py", "destination": "tools/project-forge-deployment/project_forge_deployment/entrypoint.py"},
+    {"source": "src/project_forge_deployment/environment_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_cli.py"},
+    {"source": "src/project_forge_deployment/environment_probe.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_probe.py"},
+    {"source": "src/project_forge_deployment/errors.py", "destination": "tools/project-forge-deployment/project_forge_deployment/errors.py"},
+    {"source": "src/project_forge_deployment/home_lab.py", "destination": "tools/project-forge-deployment/project_forge_deployment/home_lab.py"},
+    {"source": "src/project_forge_deployment/image_transfer.py", "destination": "tools/project-forge-deployment/project_forge_deployment/image_transfer.py"},
+    {"source": "src/project_forge_deployment/keys.py", "destination": "tools/project-forge-deployment/project_forge_deployment/keys.py"},
+    {"source": "src/project_forge_deployment/local_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_cli.py"},
+    {"source": "src/project_forge_deployment/local_runtime.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_runtime.py"},
+    {"source": "src/project_forge_deployment/local_spec.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_spec.py"},
+    {"source": "src/project_forge_deployment/local_sqlite.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_sqlite.py"},
+    {"source": "src/project_forge_deployment/portable_profile.py", "destination": "tools/project-forge-deployment/project_forge_deployment/portable_profile.py"},
+    {"source": "src/project_forge_deployment/profile_migration.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profile_migration.py"},
+    {"source": "src/project_forge_deployment/profile_repository.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profile_repository.py"},
+    {"source": "src/project_forge_deployment/profiles.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profiles.py"},
+    {"source": "src/project_forge_deployment/registry_access.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py"},
+    {"source": "src/project_forge_deployment/registry_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_cli.py"},
+    {"source": "src/project_forge_deployment/route_registry.py", "destination": "tools/project-forge-deployment/project_forge_deployment/route_registry.py"},
+    {"source": "src/project_forge_deployment/route_registry_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/route_registry_remote.py"},
+    {"source": "src/project_forge_deployment/security.py", "destination": "tools/project-forge-deployment/project_forge_deployment/security.py"},
+    {"source": "src/project_forge_deployment/sqlite_adapter.py", "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter.py"},
+    {"source": "src/project_forge_deployment/sqlite_adapter_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter_remote.py"},
+    {"source": "src/project_forge_deployment/sqlite_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_cli.py"},
+    {"source": "src/project_forge_deployment/sqlite_import_recovery.py", "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_import_recovery.py"},
+    {"source": "src/project_forge_deployment/ssh.py", "destination": "tools/project-forge-deployment/project_forge_deployment/ssh.py"},
+    {"source": "src/project_forge_deployment/teardown.py", "destination": "tools/project-forge-deployment/project_forge_deployment/teardown.py"},
+    {"source": "src/project_forge_deployment/teardown_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_cli.py"},
+    {"source": "src/project_forge_deployment/teardown_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_remote.py"},
+    {"source": "src/project_forge_deployment/trust.py", "destination": "tools/project-forge-deployment/project_forge_deployment/trust.py"},
+    {"source": "docs/DEVELOPER_ENVIRONMENTS.md", "destination": "docs/project-forge/DEVELOPER_ENVIRONMENTS.md"},
+    {"source": "docs/WORKSPACE_INSTANCES.md", "destination": "docs/project-forge/WORKSPACE_INSTANCES.md"},
+    {"source": "docs/ENVIRONMENT_PROOF.md", "destination": "docs/project-forge/ENVIRONMENT_PROOF.md"},
+    {"source": "docs/images/developer-environment-journey.svg", "destination": "docs/project-forge/images/developer-environment-journey.svg"},
+    {"source": "docs/images/personal-environment-architecture.svg", "destination": "docs/project-forge/images/personal-environment-architecture.svg"},
+    {"source": "docs/images/poc-environment-model.svg", "destination": "docs/project-forge/images/poc-environment-model.svg"}
+  ]
+}