Katas Examples

Example scopes can include a katas.yml file to demonstrate reusable procedures alongside rules.

python-general katas

# example-daimyo-rules/python-general/katas.yml
python:
  testing:
    when: "When starting a TDD cycle for a Python function"
    katas:
      tdd-cycle: |
        1. Write a failing test for the target behaviour. Run `pytest -x` — confirm it fails.
        2. Write the minimal implementation to make it pass. Run `pytest -x` — confirm it passes.
        3. Refactor for clarity without changing behaviour. Run `pytest` — confirm all tests pass.

team-backend katas

team-backend overrides the tdd-cycle kata with a backend-specific variant. The child procedure completely replaces the parent's — this is the override-by-name semantics in practice:

# example-daimyo-rules/team-backend/katas.yml
python:
  testing:
    when: "When starting a TDD cycle for a backend service endpoint"
    katas:
      tdd-cycle: |
        1. Write a failing integration test for the endpoint. Run `pytest -x -m integration` — confirm it fails.
        2. Implement the handler with the minimum logic required. Run `pytest -x -m integration` — confirm it passes.
        3. Add unit tests for edge cases. Run `pytest` — confirm all tests pass.
        4. Run `ruff check .` and fix any linting issues before committing.

When a consumer requests project-api (which inherits from team-backend), the merged tdd-cycle is the backend variant. The python-general procedure is no longer visible.

fcyaml flowchart kata

A #!fcyaml kata models a multi-path workflow as a typed node graph. Daimyo parses it and renders numbered markdown steps automatically — including retry annotations on back-edges and parallel branch annotations for fork/sync pairs.

# example-daimyo-rules/project-api/katas.yml
ci:
  pipeline:
    when: "When running the CI/CD pipeline for a release"
    katas:
      ci-pipeline: |
        #!fcyaml
        flowchart:
          name: "CI/CD Pipeline"
          nodes:
            - id: START
              type: terminator
              description: "Begin pipeline"
              next: BUILD

            - id: BUILD
              type: process
              description: "Build and package the application"
              role: "DevOps Engineer"
              outputs: ["artefact"]
              next: TESTS_FORK

            - id: TESTS_FORK
              type: fork
              description: "Run test suites in parallel"
              branches: [UNIT_TESTS, INTEGRATION_TESTS]

            - id: UNIT_TESTS
              type: process
              description: "Execute unit test suite"
              next: TESTS_SYNC

            - id: INTEGRATION_TESTS
              type: process
              description: "Execute integration test suite"
              next: TESTS_SYNC

            - id: TESTS_SYNC
              type: sync
              description: "Wait for all test suites to complete"
              next: QUALITY_GATE

            - id: QUALITY_GATE
              type: decision
              condition: "Do all tests pass?"
              alternatives:
                - case: "Yes"
                  next: DEPLOY
                - case: "No"
                  next: BUILD

            - id: DEPLOY
              type: predefined_process
              description: "Automated staging deployment pipeline"
              inputs: ["artefact"]
              next: END

            - id: END
              type: terminator
              description: "Pipeline complete — release shipped"

When fetched via get_kata("ci-pipeline"), this renders as:

## CI/CD Pipeline

1. **[Start/End]** Begin pipeline. Continue to step 2.
2. **[Process]** Build and package the application. Assigned to DevOps Engineer. Produces: <artefact>. Continue to step 3.
3. **[Fork]** Run test suites in parallel. Start steps 4 and 5 simultaneously; converge at step 6.
4. **[Process]** *(Branch 1)* Execute unit test suite. Continue to step 6 (sync).
5. **[Process]** *(Branch 2)* Execute integration test suite. Continue to step 6 (sync).
6. **[Sync]** Wait for all test suites to complete. Continue to step 7.
7. **[Decision]** Do all tests pass?
   - Case "Yes": Continue to step 8.
   - Case "No": Return to step 2 (retry).
8. **[Sub-process]** Automated staging deployment pipeline. Uses: <artefact>. Continue to step 9.
9. **[Start/End]** Pipeline complete — release shipped. End of procedure.

## Node Type Reference

- **[Start/End]**: Marks the start or end of the procedure. The first node declared is the entry point; an end node omits the `next` field.
- **[Process]**: A standard automated or system step. `role` names who or what is responsible; `inputs` lists data consumed; `outputs` lists data produced; `next` is the following step.
- **[Decision]**: A branching point. `condition` states the question asked; each `alternative` entry pairs a `case` label with a `next` target step.
- **[Sub-process]**: Invokes a named sub-procedure defined elsewhere. Same parameters as Process.
- **[Fork]**: Splits execution into parallel branches. `branches` lists the first node ID of each branch; all run simultaneously before converging at a Sync node.
- **[Sync]**: Marks where parallel branches converge. Execution resumes only after all branches complete. `next` is the step that follows.

Exploring the Examples

# View kata category index
curl http://localhost:8000/api/v1/scopes/python-general/katas/index

# List katas filtered by category
curl "http://localhost:8000/api/v1/scopes/project-api/katas?categories=python.testing"

# Retrieve a specific kata procedure
curl http://localhost:8000/api/v1/scopes/project-api/katas/tdd-cycle