New Project Onboarding

When you spawn a new project from this monorepo starter template, you need to register it with the WS.Eng tooling so that the CLI, codemap, context packs, and documentation workflows all work correctly.

This guide covers the steps to go from a freshly forked/cloned repo to a fully integrated WS.Eng project.

Prerequisites

• WS.Eng CLI installed and linked globally (wseng --help to verify). See ws-eng-cli README for installation.
• GitHub CLI (gh) authenticated with access to the trilogy-group organization.
• Access to the WS.Eng AWS account (856284715153) with a configured AWS CLI profile.

Step 1: Replace Placeholders

Follow the Setup instructions in the README to replace all template placeholders:

• ws-mono-st → your short project name (max 12 chars, lowercase, dash-separated)
• wseng-monorepo-starter → your full project name
• WS.Eng Monorepo Starter → your project display name

Step 2: Initialize the WS.Eng CLI

From the root of your new repository:

wseng init

This command does several things:

1. Creates .wseng in the repo root if it doesn't already exist (the starter template ships with one, so init will skip this step and preserve the existing file).
2. Configures your local environment: sets up AWS credentials, Google auth, and Cursor CLI tools.
3. Adds entries to .gitignore: .context, .aider*, .vscode/settings.json.
4. Registers the repo in your personal CLI config (localPaths): maps the repo name to its local path. This is critical — wseng ws build-codemap uses localPaths to discover repositories when run outside a git repo.

Verify and Update the .wseng Configuration

After initialization, open the .wseng file in the repo root. The starter ships with default values, but you need to customize it for your project:

{
  "contextFolder": ".context",
  "specs": [],
  "pullRequestTemplate": "{{ ticketUrl }}",
  "defaultGitHubRepo": "your-project-name",
  "commandConfigurations": {
    "release-notes": {
      "defaultInputs": {
        "chatSpace": "Your Chat Space Name",
        "workflowName": "Deploy Production"
      }
    }
  }
}

Key fields to configure:

• defaultGitHubRepo: Set this to your repository name (e.g., your-project) so ticket commands can resolve numeric-only IDs without the repo/ prefix. This field is not included in the default template — you must add it manually.
• contextFolder: Defaults to ".context". This is where the CLI stores per-ticket working state (estimations, ticket metadata). It is not where context packs live (see Step 3).
• commandConfigurations.release-notes: Update the chatSpace to your project's Google Chat space name.

Step 3: Create Context Packs

Context packs are Markdown files with YAML front matter that describe your project's products, modules, and playbooks. The CLI discovers them by filename pattern from anywhere in the repository — they are not stored in a single config file. Place them in your docs/ directory (or any subdirectory) for discoverability.

How Context Packs Are Discovered

The CLI scans the entire repository root for files matching these glob patterns:

Files matching **/*template.md are excluded.

L1 — Product Context Pack (Required)

Every project needs at least one L1 file. This defines the product that the codemap and CLI commands reference.

Filename: L1.<product-name>.context.md (e.g., L1.my-project.context.md)

Required front matter:

---
type: product
name: my-project
description: 'A brief description of your product'
docsRoot: docs/
scripts:
  check: []
  fix: []
  test: []
files:
  cicd:
    include: ['.github/**']
  docs:
    include: ['docs/**']
  iac:
    include: ['infra/**']
---

The Markdown body below the front matter is the product's context content — used by the CLI when generating code or answering questions.

L2 — Module Context Pack (Required for Codemap Modules)

Each module in your project gets an L2 file. Modules must reference an existing L1 product by name.

Filename: L2.<module-name>.context.md (e.g., L2.backend.context.md)

Required front matter:

---
type: module
name: backend
product: my-project
description: 'Hono REST API backend with DynamoDB'
scripts:
  check: []
  fix: []
  test:
    - cwd: '.'
      script: 'pnpm test'
files:
  sources:
    include: ['backend/**']
    exclude: ['backend/**/*.test.ts']
  cicd:
    include: []
  docs:
    include: []
  iac:
    include: ['infra/constructs/backend.construct.ts']
---

L3 — Function Context Pack (Optional)

L3 files document individual functions within a module. They do not require YAML front matter — the CLI identifies the product and module from the filename.

Filename pattern: L3.<module-name>.<function-name>.context.md

Example: L3.backend.create-user.context.md

The CLI matches <module-name> to an existing L2 module. If no module match is found but only one product and one module exist in the repo, the L3 file is auto-associated with them.

PB — Playbook Context Pack (Optional)

Playbooks document operational procedures, troubleshooting runbooks, or process guides.

Filename: PB.<playbook-name>.md (e.g., PB.deployment-rollback.md)

Required front matter:

---
type: playbook
name: deployment-rollback
product: my-project
description: 'How to roll back a failed production deployment'
---

Recommended File Placement

Place context packs inside docs/ to keep them organized and co-located with your project documentation:

docs/
├── L1.my-project.context.md        # Product definition
├── L2.backend.context.md           # Backend module
├── L2.frontend.context.md          # Frontend module
├── L2.infrastructure.context.md    # Infrastructure module
├── L3.backend.create-user.context.md  # Function-level (optional)
├── PB.deployment-rollback.md       # Playbook (optional)
├── guides/                         # Scalar documentation guides
│   ├── introduction.md
│   └── ...
└── assets/

Additional Context Sources

• Cursor rules in .cursor/rules/ also act as context for AI-assisted development. The starter includes rules for naming conventions, dependency injection, backend patterns, and more. Review and customize these for your project.
• Additional document types can be placed in named subdirectories (second-brains/, quality-bars/, playbooks/, brain-lifts/) for discovery by the sync-context-documents command.

Step 4: Build the Codemap

The codemap is a structural index that maps your repository's products and modules. The CLI uses it for code navigation, dependency analysis, and AI-assisted development.

Prerequisites

Before building the codemap, you must have created:

1. At least one L1 (product) context pack with valid front matter (type: product, name)
2. At least one L2 (module) context pack with valid front matter (type: module, name, product)

The build-codemap command calls loadMetadataFromContextPacks() which parses L1 and L2 files (L3 files are skipped during codemap generation). For each L1 file, it creates a CodeMapProduct entry; for each L2 file, it creates a CodeMapModule entry linked to its product.

Building the Codemap

From the repository root:

wseng ws build-codemap

This will:

1. Scan the repository for L1 and L2 context pack files
2. Parse their YAML front matter to extract product and module metadata
3. Build a codemap structure: { repo → { products, modules } }
4. Push the codemap to GitHub (via the CodemapService)

If you are not inside a git repository when you run this command, it will instead scan all repositories defined in your personal CLI configuration (localPaths).

Verify Before Pushing

Run without pushing to verify the codemap locally first:

wseng ws build-codemap --no-push

What the Codemap Contains

For each repository, the codemap records:

The codemap enables commands like:

• wseng context-tree — Generate dependency trees for files
• wseng question — Answer questions about the codebase
• wseng implement — AI-assisted implementation using codebase understanding

When to Rebuild

Rebuild the codemap after:

• Adding or removing L1/L2 context pack files
• Renaming products or modules in context pack front matter
• Adding new workspace packages or backend modules
• Major refactors that change directory structure

Step 5: Register in the Team Roster

The WS.Eng Team Roster is a Google Sheet that tracks all active projects, their repositories, and team assignments. Your project must be registered here for cross-project CLI commands to work (e.g., wseng ws clone-repositories, wseng sync-context-documents, wseng ws project-updates).

Access: The Team Roster requires membership in the WorkSmart Engineering Google group. If you don't have access, request it in the "WS.Eng Access Requests" Google Chat space.

Adding Your Project

There is no CLI command to add entries to the Team Roster — it is managed manually in the Google Sheet. You will need to add rows to the following sheets:

1. Projects sheet — Optional, add a row with:

   • ID: A unique project identifier (e.g., YourProject)
   • Short Name: An abbreviation (e.g., YP)
   • Friendly Name: Human-readable project name
   • Company: The parent company
   • Product: The product name (should match the name in your L1 context pack)

2. Repositories sheet — Add a row for your new repository with:

   • Name: Repository name (e.g., your-project)
   • Description: Brief description
   • URL: Full GitHub URL (e.g., https://github.com/trilogy-group/your-project)
   • Type: Repository type
   • Project: Must match the Project ID from the Projects sheet

After Registration

Once registered, team members can clone all project repositories at once:

wseng ws clone-repositories

Registration also enables the wseng sync-context-documents command to discover your repository's context packs and catalog them in the Team Roster's "Context Documents" sheet. This is a team-level maintenance command (not a project setup step) that scans all registered repositories for L1/L2/L3 context pack files and documents in second-brains/, quality-bars/, playbooks/, and brain-lifts/ directories.

Step 6: Set Up Scalar Documentation

If you want your own Scalar documentation site (separate from the starter's):

# Install Scalar CLI (one-time)
npm i -g @scalar/cli

# Authenticate with your team's Scalar token
scalar auth login --token=<SCALAR_TOKEN>

# Create a new Scalar project
scalar project create --name "Your Project Docs" --slug your-project-docs

Then update .doc.json:

{
  "meta": {
    "title": "Your Project Docs",
    "description": "Documentation for Your Project."
  },
  "targets": {
    "scalar": {
      "projectSlug": "your-project-docs"
    }
  }
}

Update the specPath in the references section to point to your project's deployed OpenAPI endpoint.

Step 7: Configure CI/CD

The CI/CD workflows reference specific values that need updating for your project:

1. AWS IAM Role ARN in base-deploy.yml — Update the default aws-role to your project's deploy role.
2. Secret ID — Create secrets in AWS Secrets Manager following the structure in the README.
3. Domain names — Update infra/app.ts with your project's domain and subdomain names.
4. Certificate ARNs — Update infra/app.ts with your project's ACM certificate ARNs.

Checklist

Use this checklist when onboarding a new project:

• Replace all placeholders (ws-mono-st, wseng-monorepo-starter, WS.Eng Monorepo Starter)
• Run wseng init and configure .wseng
• Set defaultGitHubRepo in .wseng
• Create an L1 product context pack (docs/L1.<product>.context.md) with valid front matter
• Create L2 module context packs (docs/L2.<module>.context.md) for each module
• Run wseng ws build-codemap --no-push to verify context packs parse correctly
• Run wseng ws build-codemap to push the codemap to GitHub
• Ensure access to the WS.Eng Team Roster (join WorkSmart Engineering Google group if needed)
• Add project to the Team Roster: Projects, Repositories, and People sheets
• Create a Scalar project (scalar project create)
• Update .doc.json with new project slug and spec URL
• Create AWS Secrets Manager entries
• Update infra/app.ts with domain names, certificate ARNs, and AWS accounts
• Deploy the integration environment (git push to main)
• Verify docs publish on first integration deploy