@copoint-ai/waypoint-cli

WayPoint

██╗    ██╗ █████╗ ██╗   ██╗██████╗  ██████╗ ██╗███╗   ██╗████████╗
██║    ██║██╔══██╗╚██╗ ██╔╝██╔══██╗██╔═══██╗██║████╗  ██║╚══██╔══╝
██║ █╗ ██║███████║ ╚████╔╝ ██████╔╝██║   ██║██║██╔██╗ ██║   ██║
██║███╗██║██╔══██║  ╚██╔╝  ██╔═══╝ ██║   ██║██║██║╚██╗██║   ██║
╚███╔███╔╝██║  ██║   ██║   ██║     ╚██████╔╝██║██║ ╚████║   ██║
 ╚══╝╚══╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝      ╚═════╝ ╚═╝╚═╝  ╚═══╝   ╚═╝

AI-driven development framework for Claude Code

WayPoint bridges the gap between product vision and working code by combining structured specification workflows with AI agent personas. It generates project scaffolding, Claude Code slash commands, and specialized agents that guide you through discovery, specification, architecture, planning, implementation, and review.

Why WayPoint?

Modern AI coding assistants are powerful but lack context. They don't know your architecture patterns, testing conventions, or quality standards. Every conversation starts from scratch.

WayPoint solves this by:

• Generating a project constitution that captures your stack, architecture, and quality standards
• Creating specialized agent personas that embody different roles (analyst, architect, developer, QA)
• Providing slash commands for each phase of development
• Embedding few-shot examples so Claude writes code that matches your patterns

The result: Claude Code sessions that understand your project from the first prompt.

Features

Workflow Phases

WayPoint structures development into clear phases, each with a dedicated slash command:

Phase	Command	Agent	Purpose
Discover	/waypoint.discover	Analyst	Explore requirements, risks, constraints
Brainstorm	/waypoint.brainstorm	Brainstorm Coach	Creative ideation with proven techniques
Constitute	/waypoint.constitute	Architect	Review project principles
Specify	/waypoint.specify	Product Manager	Create feature specifications
Clarify	/waypoint.clarify	Analyst	Resolve ambiguities
Architect	/waypoint.architect	Architect	Design technical solutions
Plan	/waypoint.plan	Scrum Master	Break into executable tasks
Implement	/waypoint.implement	Developer	Write code following patterns
Review	/waypoint.review	QA	Verify quality and compliance

Agent Personas

Each agent has a distinct personality, responsibilities, and commands:

Agent	ID	Role
Analyst	/waypoint.agents.analyst	Requirements discovery and risk identification
Brainstorm Coach	/waypoint.agents.brainstorm	Creative ideation and innovation facilitation
Product Manager	/waypoint.agents.pm	Specifications and user stories
Architect	/waypoint.agents.architect	System design and ADRs
Scrum Master	/waypoint.agents.sm	Task breakdown and dependencies
Developer	/waypoint.agents.dev	Implementation following patterns
QA Engineer	/waypoint.agents.qa	Code review and quality gates
Module Architect	/waypoint.agents.modarch	Extending WayPoint itself

Supported Stacks

Full-Stack Frameworks

• Next.js (App Router) - TypeScript
• Express.js + TypeScript
• FastAPI - Python
• Django - Python
• ASP.NET Core Web API - C#

Libraries / Plain Languages

• Plain TypeScript
• Plain JavaScript
• Plain Python
• Plain C#

Architecture Patterns

• Clean Architecture - Onion-style with domain at center
• Domain-Driven Design (DDD) - Tactical patterns with aggregates
• MVC with Interactors - Classic MVC enhanced with use cases
• Simple Layered - Routes → Services → Data

Installation

For Internal Users (GitHub Packages)

See Internal Installation Guide for one-time authentication setup.

npx @copoint-data/waypoint-cli@alpha init

For Development

git clone https://github.com/CoPoint-Data/waypoint-cli.git
cd waypoint-cli
npm install
npm run build
npm link

Quick Start

1. Initialize a new project

npx @copoint-data/waypoint-cli@alpha init

This launches an interactive wizard that asks about:

• Project name and type (greenfield/brownfield)
• Technology stack (Next.js, FastAPI, etc.)
• Architecture pattern (Clean, DDD, MVC, Simple)
• Database and ORM
• Testing frameworks

2. Explore generated files

your-project/
├── .claude/
│   └── commands/           # Claude Code slash commands
│       ├── waypoint.discover.md
│       ├── waypoint.specify.md
│       ├── waypoint.architect.md
│       └── ...
│       └── waypoint/
│           └── agents/     # Agent personas
│               ├── dev.md
│               ├── pm.md
│               └── ...
├── .waypoint/
│   ├── constitution.md     # Project principles (READ FIRST)
│   ├── config.yaml         # Project configuration
│   ├── templates/          # Document templates
│   ├── specs/              # Generated specifications
│   ├── plans/              # Technical plans
│   └── tasks/              # Executable tasks
└── CLAUDE.md               # Project memory for Claude

3. Start a Claude Code session

claude

Claude automatically reads CLAUDE.md and understands your project context.

4. Use workflow commands

> /waypoint.discover

I'll adopt the Analyst persona and help explore your requirements...

5. Activate agent personas

> /waypoint.agents.dev

🎭 Developer Agent Activated

I'm now operating as your Senior Developer. I'll implement features
following Clean Architecture patterns and write tests with Vitest.

Available commands:
- implement {task}: Implement a specific task
- test: Run tests for current work
- lint: Run linter and fix issues
- refactor {target}: Refactor following patterns
- exit: Exit developer persona

How It Works

The Constitution

Every WayPoint project has a constitution (.waypoint/constitution.md) that defines:

• Technical stack - Framework, language, database, ORM
• Architecture principles - Layer rules, dependency direction
• Quality standards - Testing requirements, linting, type checking
• Security principles - Input validation, secrets management
• Anti-patterns - What to avoid and how to fix violations

All agents reference this constitution, ensuring consistent guidance.

Few-Shot Examples

Agent files include code examples specific to your stack + architecture combination:

## Code Examples

### Entity (Domain Layer)
\`\`\`typescript
// domain/entities/user.ts
export class User {
  constructor(
    public readonly id: UserId,
    public readonly email: Email,
    private passwordHash: string
  ) {}

  verifyPassword(password: string): boolean {
    return bcrypt.compareSync(password, this.passwordHash)
  }
}
\`\`\`

These examples teach Claude your exact patterns.

Template-Driven Documents

WayPoint generates templates for specifications, plans, and tasks:

• Spec Template - User scenarios, requirements, acceptance criteria
• Plan Template - Architecture alignment, component design, API contracts
• Task Template - Context, objective, acceptance checklist
• Story Template - User story format with testing requirements

Commands Reference

CLI Commands

npx @copoint-data/waypoint-cli@alpha init        # Initialize new project
npx @copoint-data/waypoint-cli@alpha init --yes  # Use defaults (detect from directory)
npx @copoint-data/waypoint-cli@alpha extend      # Add new stacks/architectures (coming soon)

Claude Code Slash Commands

Command	Description
/waypoint.discover	Start discovery phase with Analyst
/waypoint.constitute	Review project constitution
/waypoint.specify	Create feature specification
/waypoint.clarify	Resolve specification ambiguities
/waypoint.architect	Create technical design
/waypoint.plan	Break design into tasks
/waypoint.implement	Implement a task
/waypoint.review	QA review implementation
/waypoint.extend	Add new modules to WayPoint

Agent Commands

Each agent supports these commands when activated:

Command	Description
help	Show available commands
exit	Exit current persona

Plus role-specific commands like discover, spec, design, implement, review, etc.

Configuration

config.yaml

project:
  name: my-project
  type: greenfield
  track: standard

stack:
  id: nextjs-app-router
  language: typescript

database:
  type: postgresql
  orm: prisma
  migrations: prisma migrate dev

auth:
  strategy: jwt
  provider: custom

architecture:
  primary: clean-architecture

testing:
  unit: vitest
  e2e: playwright
  linter: biome
  formatter: biome
  typeChecker: tsc

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format

# Full check (typecheck + lint + test)
npm run check

Project Structure

src/
├── domain/              # Core business logic
│   ├── entities/        # Project, Stack, Architecture, Agent
│   ├── value-objects/   # FilePath, Identifier, Version
│   └── interfaces/      # Repository interfaces
├── application/         # Use cases and services
│   ├── ports/           # Generator interfaces
│   └── services/        # Generator implementations
├── infrastructure/      # External concerns
│   └── file-writer.ts   # File system operations
└── presentation/        # CLI and data
    ├── cli/             # Commander.js CLI
    └── data/            # Stack/Architecture registries

Extending WayPoint

WayPoint is designed to be extended with new stacks, architectures, and modules.

Adding a New Stack

• Add stack definition to src/presentation/data/stacks/index.ts
• Include compatible ORMs and auth strategies
• Provide few-shot code examples
• Define file structure conventions

Adding a New Architecture

• Add architecture definition to src/presentation/data/architectures/index.ts
• Define layers with rules and responsibilities
• List anti-patterns with fixes
• Provide stack-specific implementations with examples

Philosophy

WayPoint is built on these beliefs:

• Context is king - AI assistants need project context to be useful
• Patterns over prompts - Few-shot examples beat lengthy instructions
• Phases structure thinking - Discovery → Specification → Architecture → Implementation
• Agents embody expertise - Different roles bring different perspectives
• Constitutions ensure consistency - Shared principles across all interactions

Discover → Specify → Architect → Plan → Implement → Review
by CoPoint AI