Getting Started with Directive

From zero to your first AI-assisted change — install the CLI, create a project, and run through the full spec-driven workflow.

Getting Started

This guide walks you through the full Directive workflow: install the CLI, create a project, configure your IDE, set context, and complete a first change from proposal to archive.

IDE covered: GitHub Copilot (VS Code). Cursor, Claude Code, Windsurf, and other supported IDEs follow the same workflow but are configured differently — directive new sets up the correct files automatically when you select your tool.

Scope: By the end of this guide you will have run through the spec-driven workflow once end-to-end. You will not have a deployed PHP application — the goal is to see the workflow work, not to ship production code.

Step 1 — Install Directive CLI

Install once globally on your machine:

composer global require cceconi/directive-cli

Verify the installation:

directive --version

Expected output: a version string such as Directive CLI 1.0.0.

Fallback: If directive conflicts with an existing binary on your system, use directive-cli instead — it is installed automatically alongside directive.

Step 2 — Create a new project

Run directive new with your project name (kebab-case):

directive new my-app

The CLI asks a few questions:

Expected output: a new my-app/ directory in the current folder with the full hexagonal structure and IDE files pre-configured:

my-app/
  .env                        ← environment variables template
  .github/
    prompts/                  ← workflow prompt files (/dtsx-*)
  bin/                        ← console entry point
  directive-spec/
    brainstorm/
    changes/
    context/
    specs/
  docker/                     ← if Docker was selected
  phpstan.neon
  public/                     ← web entry point
  src/
    Application/
    Domain/
    Infrastructure/
      Config/
        AppConfig.php
      Console/
      ConsoleApplication.php
      Http/
      Persistence/
      Security/
      WebApplication.php
  tests/
  var/                        ← runtime cache and logs
  composer.json

Step 3 — Open the project in VS Code

cd my-app && code .

Open the Copilot Chat panel (Ctrl+Alt+I or the chat icon in the activity bar).

The workflow prompt files in .github/prompts/ were generated by directive new. They power the /dtsx-* slash commands — no manual setup needed.

Expected: Copilot Chat is available and the /dtsx-* slash commands are recognised.

Step 4 — Set project context

Before creating any changes, tell the agent about your domain and stack. These are one-time setup commands — run them once per project, update them if the project changes significantly.

In Copilot Chat, run:

/dtsx-project

The agent asks three questions sequentially:

1. What is the domain of this project? (e.g. e-commerce platform for independent retailers)
2. Who are the main users? (e.g. store owners and their customers)
3. What are the main bounded contexts? (e.g. catalog, orders, payments)

Answer each before the agent moves to the next. The agent writes the answers to directive-spec/context/.

Expected: directive-spec/context/common.yaml created (or updated) with your domain definition.

Then add your stack:

/dtsx-stack php

The agent records your PHP version, key libraries, and conventions.

Expected: directive-spec/context/php.yaml created with PHP-specific rules, and a reference added in directive-spec/context/common.yaml.

For full details on these commands, see slash-commands-context.md.

Step 5 — Propose a first change

Pick something small and concrete — for example, a health-check endpoint, a domain entity, or a simple use case. Then run:

/dtsx-propose add-health-check

The agent creates a change directory at directive-spec/changes/add-health-check/ and writes all four artifacts in one pass:

Expected: The agent confirms all four artifacts are done and the change is ready to apply.

For full details, see /dtsx-propose in the lifecycle reference.

Step 6 — Apply the change

/dtsx-apply add-health-check

The agent reads the specs and tasks, then works through each task one by one:

• Writes PHP code against the specs
• Runs static analysis (phpstan at level 8) after each code task
• Checks off each task in tasks.md as it completes it

Expected: all tasks in tasks.md are marked [x], the agent reports progress as it goes, and phpstan exits with 0 errors.

If a task is unclear or blocked, the agent pauses and explains — it does not guess.

For full details, see /dtsx-apply in the lifecycle reference.

Step 7 — Archive the change

Once all tasks are complete:

/dtsx-archive add-health-check

The agent:

1. Syncs delta specs from directive-spec/changes/add-health-check/specs/ into directive-spec/specs/
2. Moves the change directory to directive-spec/changes/archive/

Expected: directive-spec/changes/archive/<date>-add-health-check/ exists, and the corresponding spec files appear in directive-spec/specs/.

The change is done and archived. Your spec history is permanent.

Next steps

You have run through the full Directive workflow once. From here:

• Brainstorm a larger feature — use /dtsx-discuss to capture intent conversationally, then /dtsx-evaluate to break it into ordered changes
• Explore all commands — Context commands reference and Lifecycle commands reference document every slash command in detail
• Check implementation quality — use /dtsx-verify after applying to validate implementation against specs
• Capture architectural decisions — use /dtsx-learn to write context files that improve future agent outputs