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 status
wwg maintain
wwg brief

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.

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
• CI Commands
• Governance
• Agent-First Markdown
• Generated Project Upgrade Path
• Contribution Loop
• Governed Skills
• 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.1. 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, changelog governance, README governance, certification, local Wizard setup, explicit GitHub publish readiness, agent readiness checks, human-led agent team governance templates, Vorter runtime skill candidate handoffs, 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.