---
name: straion-implement
description: |
  Guides users through rules-first feature implementation from idea to production code. Validates specs, tasks, and implementation against project rules at every step. Use when building features, implementing specs, creating implementation plans, breaking down specs into tasks, or when user says "help me build", "implement this", "add feature", "plan this", "break down this spec", "create tasks", or wants rules compliance.
---

# Developing with Rules

## Core Philosophy

- **Rules First**: Build features that meet documented rules
- **Systematic Validation**: Validate at every level to catch issues early
- **Guided Process**: Clear structure while remaining flexible

## Workflow

### Step 1: Idea → Specification

Transform a rough idea into a clear, lightweight specification.

1. Understand the request — ask clarifying questions when ambiguous
2. Create a lightweight spec covering:
   - Overview, Goals, Scope
   - Key Rules (must-have vs nice-to-have)
   - Acceptance Criteria, Technical Approach
   - Open Questions

### Step 2: Validate Specification

Ensure the spec complies with project rules BEFORE planning.

Run the Straion CLI to find matching rules:

```bash
straion find-rules \
  --title "<spec title>" \
  --body "<full spec content>" \
  --summary "<brief summary>" \
  --files "<key files involved>" \
  --tags "<applicable scope tags>" \
  --keywords "<relevant technical keywords>"
```

- `--title` (required) with a short title of the spec, task, or change
- `--body` (required) with the detailed description of the spec, task, or change
- `--summary` with higher-level context (the overall plan or feature)
- `--files` with the key files involved (languages are derived from extensions)
- `--tags` with applicable scope tags (e.g. `api,domain,testing,security`)
- `--keywords` with relevant technical keywords (e.g. `jwt,auth,caching`)

`straion find-rules` prints each rule prefixed with a short `[shortcode]`, e.g.
`- [3kQ9fX2a] Users must be able to log in with email and password`. Copy the
shortcode verbatim from the CLI output — it is what links a decision back to its
rule, so never invent or paraphrase one.

Record a decision for **every** rule it returned, using the `record_verdict` tool:

```
record_verdict(
  verdicts: [
    {
      shortcode:  "3kQ9fX2a",
      assessment: "violation",
      decision:   "fix",
      reason:     "will add the missing input validation in this change"
    },
    { shortcode: "7mPq2LxR", assessment: "compliant" }
  ]
)
```

Writing your conclusion in a message records nothing. Only this tool does.

Record every rule you have judged in one call.

**`assessment`** is your judgement of whether the rule was met:

| Value       | Meaning                                       |
| ----------- | --------------------------------------------- |
| `compliant` | The rule is met.                              |
| `partial`   | Partly met. Treated exactly like `violation`. |
| `violation` | The rule is broken.                           |

**`decision`** is what happens about a violation. Required for `partial` and
`violation`. Leave it unset for `compliant` — a rule that is met has
nothing to decide, and the pair is refused:

| Value            | Meaning                                 |
| ---------------- | --------------------------------------- |
| `fix`            | You will correct it in this change.     |
| `accept`         | It ships broken, on purpose.            |
| `not-applicable` | The rule does not apply to this change. |

**Propose `fix` unless the person has already said otherwise.** `fix` and
`compliant` are recorded silently. `accept` and `not-applicable` interrupt the
person with an approval prompt, so never reach for them on your own initiative —
they are for decisions a person has already made.

You cannot end a turn while any rule is unresolved: one with no
decision, one marked `fix` that is still broken, or one whose files changed
since you decided. If a violation is one you cannot fix, say so in conversation
— what the rule requires, what fixing it would cost, and what you recommend —
and let the person decide. Only then record their decision.

#### When the approval prompt is rejected

Rejection means you proposed something other than what was meant, and nothing
was recorded. Do not call the tool again with the same arguments. Ask what they wanted instead, then
record that decision — most often `fix` rather than `accept`.

### Step 3: Plan & Validate Tasks

Break down the validated spec into compliant implementation tasks.

1. Explore the codebase for architecture patterns and conventions
2. Create ordered implementation tasks with acceptance criteria

**VALIDATION GATE: Each task MUST be validated before adding to plan**

3. For each task:

   - Draft task description + acceptance criteria
   - Run `straion find-rules` for this task:
     ```bash
     straion find-rules \
       --title "<task title>" \
       --body "<task description>" \
       --summary "<overall spec summary>" \
       --files "<files this task will touch>" \
       --tags "<applicable scope tags>" \
       --keywords "<relevant technical keywords>"
     ```
   - Review compliance, adjust task if violations found
   - Record a decision per rule with the `record_verdict` tool (see Step 2)

4. Address any violations or gaps across all tasks
5. Present complete, validated plan for user approval

**Do NOT present plan until all tasks pass validation**

6. Wait for user approval before implementing

### Step 4: Implement

Execute the validated tasks while maintaining compliance.

1. Track progress (use todo tracking if available)
2. Implement task by task following descriptions and validation feedback
3. For complex tasks, re-validate against rules as needed
4. Write tests and verify acceptance criteria are met
5. Once you have fixed a violation, record it again as `assessment: "compliant"`.
   A decision goes stale when the files it covered change, so the turn stays
   open until the fix is recorded.

## Workflow Modes

| Mode          | When                                  | Flow               |
| ------------- | ------------------------------------- | ------------------ |
| Full          | Starting from rough idea              | Step 1 → 2 → 3 → 4 |
| From Spec     | Have existing spec                    | Step 2 → 3 → 4     |
| Validate Only | Just check compliance                 | Step 2 only        |
| Plan Only     | Create validated implementation tasks | Step 3 only        |

## User Interaction

- **Be Conversational**: Explain what you're doing, ask when unclear
- **Be Transparent**: Show validation results, explain violations
- **Be Flexible**: Adapt to existing artifacts, skip unnecessary steps
- **Track Progress**: Use todo tracking for multi-task implementations

## Success Criteria

✅ User understands what was built and why
✅ Spec and tasks are validated
✅ Critical violations are addressed
✅ Implementation works and passes tests
✅ Solution meets rules