Tutorial: Production Readiness

Verify you're ready

This tutorial builds on the deliver output from Tutorial 9. Before starting, cd into your tutorial project and confirm:

• docs/feature/<feature-id>/deliver/ directory with completed implementation artifacts
• docs/feature/<feature-id>/design/architecture-design.md

If either is missing, complete Tutorial 9: Delivering the Feature first.

What You'll Build

A complete production readiness package -- CI/CD workflow, deployment strategy, infrastructure recommendations, and a go-live checklist -- all designed by Apex, nWave's platform architect agent.

Before: You have a fully implemented bookmark CLI from Tutorial 8. All acceptance tests pass. The code is mutation-tested and reviewed. But you have no CI/CD pipeline, no deployment plan, no monitoring strategy, and no checklist to know when it is safe to release.

After: You have a GitHub Actions workflow with quality gates at every stage. You have a deployment strategy matched to your project's risk profile. You have infrastructure recommendations for packaging and distribution. You have a production readiness checklist that tells you exactly what remains before go-live. Everything is documented and peer-reviewed.

Why this matters: Working code is not the same as shippable code. /nw-devops bridges the gap between "all tests pass" and "safe to release" by applying the same evidence-based methodology the rest of the wave used. The platform architect does not guess -- it reads your architecture, your test suite, and your deployment target, then designs infrastructure that fits.

Step 1 of 7: Confirm Your Starting Point (~1 minute)

You should be in the bookmark-cli project from Tutorial 8, with all acceptance tests passing.

Verify your tests pass:

pytest tests/ -v --no-header 2>&1 | tail -5

You should see all tests passing:

...
PASSED
PASSED

===== X passed in Y.YYs =====

Verify your architecture document exists:

ls docs/feature/bookmark-cli/design/architecture-design.md

You should see:

docs/feature/bookmark-cli/design/architecture-design.md

Verify your evolution document exists:

ls docs/evolution/

You should see:

bookmark-cli.md

If tests fail or files are missing: Complete Tutorial 8 first. /nw-devops reads architecture documents, test results, and the delivered codebase to make infrastructure decisions. Without them, the platform architect cannot assess what needs to be deployed.

Next: you will launch the devops command and answer Apex's configuration questions.

Step 2 of 7: Launch the DevOps Session (~1 minute)

In Claude Code, type:

/nw-devops bookmark-cli

AI output varies between runs. Your session with Apex will differ from the examples below. The agent designs infrastructure based on your specific architecture and deployment target. What matters is the structure (decisions, artifacts, peer review), not the exact output.

Apex (the platform architect agent) will ask eight configuration questions to tailor the infrastructure design to your project. When Apex asks each question, select the option shown below.

What just happened? Apex read your architecture documents, test suite, and codebase to understand what needs to be deployed. These eight answers configure the infrastructure design -- deployment target determines packaging, CI/CD platform determines workflow format, branching strategy determines pipeline triggers, and deployment strategy determines release mechanics. The key concept here is the interaction itself: Apex asks simple multiple-choice questions, then uses your answers plus your codebase to generate a complete infrastructure design.

Next: Apex will design the CI/CD pipeline.

Step 3 of 7: Watch the CI/CD Pipeline Design (~3 minutes)

After your answers, Apex designs a CI/CD pipeline. You will see:

● nw-platform-architect(Analyzing existing infrastructure...)
● nw-platform-architect(Designing CI/CD pipeline...)
● nw-platform-architect(Creating .github/workflows/bookmark-cli.yml)
● nw-platform-architect(Creating docs/feature/bookmark-cli/devops/ci-cd-pipeline.md)

The generated GitHub Actions workflow will look something like:

name: bookmark-cli CI/CD
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - run: pip install ruff
      - run: ruff check src/ tests/

  test:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - run: pip install -e ".[test]"
      - run: pytest tests/ -v --cov=bookmark_cli

  security:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install safety
      - run: safety check

  publish:
    needs: [test, security]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install build twine
      - run: python -m build
      - run: twine upload dist/*

Your workflow will differ. Apex tailors the pipeline to your specific architecture and test setup. The pattern is what matters: lint first, then test and security in parallel, then publish only on main.

Two things to notice:

1. Quality gates at every stage. The pipeline does not publish unless lint, tests, and security scanning all pass. This mirrors the quality gates from the delivery pipeline in Tutorial 8 -- the same discipline, applied to the release process.
2. Branch-aware triggers. Pull requests run lint, test, and security. Only pushes to main trigger publish. This matches the GitHub Flow branching strategy you selected.

Next: Apex will design the deployment strategy and infrastructure recommendations.

Step 4 of 7: Review Infrastructure and Deployment Design (~3 minutes)

After the pipeline, Apex designs deployment and infrastructure:

● nw-platform-architect(Designing deployment strategy...)
● nw-platform-architect(Creating docs/feature/bookmark-cli/devops/deployment-strategy.md)
● nw-platform-architect(Designing infrastructure recommendations...)
● nw-platform-architect(Creating docs/feature/bookmark-cli/devops/platform-architecture.md)

Check the deployment strategy:

ls docs/feature/bookmark-cli/devops/

You should see something like:

ci-cd-pipeline.md
deployment-strategy.md
platform-architecture.md
branching-strategy.md

Your file names and count may differ. Apex may split or combine documents based on complexity. Look for files covering CI/CD, deployment, and infrastructure.

The deployment strategy for a CLI tool typically covers:

• Packaging: Python wheel and sdist via python -m build
• Distribution: PyPI publish with version tagging
• Versioning: Semantic versioning aligned to conventional commits
• Rollback: Publish a patch version -- PyPI does not support unpublishing, so rollback means "release a fix fast"

What just happened? Apex applied Principle 4 (simplest infrastructure first) from its methodology. A CLI tool does not need Kubernetes, load balancers, or canary deployments. It needs a build, a publish, and a version strategy. Apex documented why simpler alternatives were chosen over complex ones.

If you see Kubernetes or container recommendations: Apex may have misread the project type. This is rare but possible. Check docs/feature/bookmark-cli/design/architecture-design.md to confirm it describes a CLI tool, not a web service.

Next: Apex will generate the production readiness checklist.

Step 5 of 7: Review the Production Readiness Checklist (~2 minutes)

Apex generates a production readiness assessment:

● nw-platform-architect(Generating production readiness checklist...)
● nw-platform-architect(Creating docs/feature/bookmark-cli/devops/production-readiness.md)

The checklist covers items like:

## Production Readiness Checklist

### Code Quality
- [x] All acceptance tests pass
- [x] Unit test coverage above 80%
- [x] Mutation testing kill rate above 80%
- [x] Adversarial code review passed

### Packaging
- [ ] pyproject.toml has correct metadata (name, version, description)
- [ ] Entry point defined (console_scripts)
- [ ] README with installation instructions
- [ ] LICENSE file present

### CI/CD
- [ ] GitHub Actions workflow committed
- [ ] Branch protection enabled on main
- [ ] PyPI API token configured as repository secret

### Security
- [ ] No hardcoded secrets in codebase
- [ ] Dependency vulnerability scan passes
- [ ] SBOM (Software Bill of Materials) generated

Your checklist will differ. Apex generates items based on what exists in your project versus what production requires. Items already completed (from tutorials 4-8) are checked. Items that still need manual action are unchecked.

The checked items are evidence the wave process already handled. The unchecked items are what remains between "working code" and "shippable product." This is the value of /nw-devops -- it tells you exactly what is left.

Next: the peer reviewer will validate the entire design.

Step 6 of 7: The Peer Review (~2 minutes)

After all designs are complete, Apex invokes Atlas (the platform architect reviewer):

● nw-platform-architect-reviewer(Review)
  Checking external validity...
  Checking pipeline quality...
  Checking deployment readiness...
  Checking observability completeness...
  Review result: APPROVED (or CONDITIONALLY_APPROVED)

The reviewer checks five dimensions:

If the reviewer requests changes, Apex fixes them automatically. You will see a second round of document updates. Maximum two rounds -- if it still fails, the pipeline stops for your manual intervention.

If you see "CONDITIONALLY_APPROVED": This means the design is sound but has medium-severity items to address before go-live. Check the review output for specific recommendations. These are typically documentation gaps, not design flaws.

Next: verify the final artifacts and see the complete wave.

Step 7 of 7: The Complete Wave (~3 minutes)

Check all the artifacts Apex produced:

find docs/feature/bookmark-cli/deliver -type f | sort

You should see something like:

docs/feature/bookmark-cli/devops/branching-strategy.md
docs/feature/bookmark-cli/devops/ci-cd-pipeline.md
docs/feature/bookmark-cli/devops/deployment-strategy.md
docs/feature/bookmark-cli/devops/platform-architecture.md
docs/feature/bookmark-cli/devops/production-readiness.md

Check for the GitHub Actions workflow:

ls .github/workflows/

You should see:

bookmark-cli.yml

Your file names will differ. What matters is the pattern: design documents explaining the "why," a workflow file implementing the "how," and a checklist tracking what remains.

bookmark-cli/
  src/bookmark_cli/
    domain/
      bookmark.py              # Entity
      services.py              # Use cases
      ports.py                 # Repository interface
    adapters/
      cli.py                   # CLI entry point
      sqlite_repository.py     # Storage implementation
  tests/
    acceptance/                # BDD scenarios (all green)
    unit/                      # TDD unit tests
  docs/
    feature/bookmark-cli/
      discover/                # Problem validation
      discuss/                 # User stories + acceptance criteria
      design/                  # Hexagonal design
      distill/                 # Test design docs
      deliver/                 # Roadmap + execution log
      devops/                  # DevOps artifacts (this tutorial)
    adrs/                      # Architecture decision records
    evolution/bookmark-cli.md  # Permanent delivery record
  .github/workflows/
    bookmark-cli.yml           # CI/CD pipeline

DISCOVER         DISCUSS          DESIGN           DISTILL          DELIVER          DEVOPS
(/nw-discover)   (/nw-discuss)    (/nw-design)     (/nw-distill)    (/nw-deliver)    (/nw-devops)
──────────────   ──────────────   ──────────────   ──────────────   ──────────────   ──────────────
"Is the problem  "What should     "How should we   "What does done  "Build it with   "Get to
 real?"           we build?"       build it?"       look like?"      quality gates"   production"

Evidence-based   User stories +   Hexagonal arch   Acceptance       Domain-first     CI/CD pipeline
validation       acceptance       + ADRs +         tests + walking  TDD + review +   + deployment +
                 criteria         diagrams         skeleton         mutation test    readiness

Tutorial 4       Tutorial 5       Tutorial 6       Tutorial 7       Tutorial 8       This tutorial

Next Steps

• Act on the checklist -- Open docs/feature/bookmark-cli/devops/production-readiness.md and work through the unchecked items. Each one brings you closer to a real release.
• Run the pipeline -- Commit the GitHub Actions workflow, push to a repository, and watch the pipeline execute. The quality gates should all pass on the first run.
• Try a different project -- Run through tutorials 4-9 again on a new idea. The wave process works the same way regardless of the feature.
• Explore standalone tutorials -- Tutorial 10: Safe Refactoring and Tutorial 11: Debugging with 5 Whys cover everyday tasks that do not require the full wave.

Troubleshooting

Last Updated: 2026-02-17