WWG

WWG is a CLI for creating agent-ready repositories where project truth, agent operating context, and validation guardrails stay separate but connected.

WWG means Wiki, Workspace, Governance. It helps new and existing projects capture durable truth, prepare implementation agents, and keep validation evidence close to the work.

Install

Recommended for most users and teams:

npm install -g @homedesk/wwg
wwg --help

Try without installing:

npx @homedesk/wwg --help

Pin WWG to a project or CI workflow:

npm install --save-dev @homedesk/wwg

A global install is the simplest way to use WWG as a workspace CLI. A dev dependency is useful when a team wants the same WWG version in a repo or CI. npx is best for one-time trial, adoption, or inspection.

When WWG is installed as a dev dependency, you can run npx wwg status, or add a package script such as "wwg": "wwg" and run npm run wwg -- status.

Start a New Project

wwg start my-project --profile saas-app
cd my-project
wwg status
wwg brief

wwg start creates the WWG operating structure first. It does not scaffold application source code.

Adopt an Existing Project

cd existing-repo
wwg adopt
wwg status
wwg brief

Adoption preserves application source code, creates or completes WWG structure, records project truth with review markers where needed, and prepares the project for agent handoff.

Existing WWG Project

wwg upgrade --check
wwg upgrade --apply
wwg doctor --apply

After a WWG package upgrade, use wwg upgrade for deterministic template/version metadata and receipt history, then wwg doctor --apply to refresh safe generated/report surfaces before validating and running wwg brief. Semantic candidate surfaces stay review-first; see Upgrade Command.

Most existing-workspace commands find the nearest parent .wwg/ automatically. Use --target <path> when you intentionally want to operate on a workspace from outside it.

For Vorter planning, run wwg vorter candidates before vorter plan; WWG generates candidate metadata only, and Vorter decides runtime activation at runtime.

How WWG Works

• Wiki = what is true
• Workspace = what agents should do now
• Governance = what must be checked
• AGENTS.md = how agents operate
• CHANGELOG.md = what meaningfully changed

Agent-First Workflow

wwg brief creates the handoff an implementation agent should read before changing the project. wwg status shows Must Have readiness, relevant Other Features, and one scoped Next action so humans and agents can see what to do next without learning every lower-level command.

Truth Reconciliation

WWG can detect scattered project evidence and create reconciliation candidates. Candidates can be approved, rejected, deferred, merged, converted to recommendations, previewed, and conservatively applied when eligible. Canonical Wiki Truth remains protected by default.

Governed UI/UX Principles

WWG owns canonical UI/UX principles, accessibility guidance, agent-interface guidance, and review checklists for HomeDesk Ecosystem apps and relevant generated workspaces. HomeDesk or the target app implements those surfaces; Vorter may later consume runtime-sensitive guidance but does not own the principles. Workspaces can override defaults through accepted WWG decisions.

See UI/UX Principle Pack for the canonical files, compact agent context, profile inclusion rules, and validation behavior.

For Agents

Before changing a WWG project, read AGENTS.md, the latest wwg brief output, Project Truth, Terminology, Current Task, and Drift Guard.

Documentation

• Quickstart
• New Project
• Existing Project Adoption
• Team Rollout Guide
• Command Reference
• Upgrade Command
• CI Commands
• Governance
• Agent-First Markdown
• Generated Project Upgrade Path
• Truth Reconciliation
• Contribution Loop
• Governed Skills
• UI/UX Principle Pack
• UI/UX Principle Pack Propagation
• Vorter Readiness
• Changelog Governance
• README Governance
• Maintenance
• Wizard
• Infrastructure
• npm Publishing
• Roadmap

Developing WWG Itself

If you are modifying the WWG package or running commands from this repository, see Developing WWG.

Current Status

Status: active template CLI and local Wizard, version 0.6.6. WWG supports public lifecycle commands, CI automation commands, generated-project setup, evidence-backed adoption, source intake, infrastructure readiness, planning, workspace/governance generation, validation, audit, status checks, maintenance review, doctor repair guidance, post-upgrade readiness guidance, changelog governance, README governance, truth reconciliation candidate and approval workflows, certification, local Wizard setup, explicit GitHub publish readiness, agent readiness checks, human-led agent team governance templates, governed specialist role templates, UI/UX principle pack propagation for selected profiles, Vorter runtime skill candidate handoffs, chained generated-project upgrade review/apply workflows, and implementation-agent briefs.

Hosted services, app source scaffolding, destructive migrations, automatic installs, cloud provisioning, deployment, automatic report cleanup, and automatic rollback remain intentionally deferred.

License

See LICENSE.