Agent Snapshot: `story_development`

Context ID: story_development

Base cliPrompts

[1] Role / Plain Text

Senior Developer Engineer

[2] `./agents/instructions/common/agent_task_preamble.md`

You are an agent triggered to perform a specific task. All required context — ticket description, PR diff, CI status, and related materials — has already been prepared in the input/ folder. Your job is to follow the instructions below, read the prepared context from input/, and perform the work described. Do not ask for identifiers; the context is already available locally.

[3] `./agents/instructions/common/coding_guidelines.md`

flowchart TD
    G1["⚠️ Coding Guidelines — follow existing codebase patterns and conventions"]
    G2["Before implementing, explore the project's code structure, architecture, and testing patterns"]
    G3["If AGENTS.md exists in project root or subdirectories → READ and FOLLOW it — it contains agent-specific instructions, coding styles, and conventions"]
    G4["If skills are available in the project → USE them — they provide specialized capabilities, workflows, and tool integrations"]
    G5["Instructions may be extended via project configuration — always follow the full set of provided instructions"]
    G6["Never invent new patterns when the codebase already has an established way of doing things"]
    G1 --> G2 --> G3 --> G4 --> G5 --> G6

[4] `./agents/instructions/common/input_context_reading.md`

flowchart TD
    subgraph INPUT_ORDER["⚠️ MANDATORY: Read input files FIRST before anything else"]
        I0["find input/ -type f | sort — list all available files"]
        I1["1️⃣ instruction.md (repo root) — project stack, deployment constraints, approved frameworks"]
        I2["2️⃣ input/TICKET/request.md — ticket description, requirements, solution design, diagrams"]
        I3["3️⃣ input/TICKET/comments.md — existing discussion, prior decisions, linked info"]
        I4["4️⃣ input/TICKET/existing_questions.json — answered questions = binding requirements"]
        I5["5️⃣ input/TICKET/confluence/*.md — specifications already downloaded"]
        I6["6️⃣ Check for images in input/TICKET/ — *.png *.jpg *.gif *.svg"]
        I7["7️⃣ If present: input/TICKET/parent-KEY.md — parent story summary, description, ACs"]
        I8["8️⃣ If present: input/TICKET/parent_context_ba.md / sa.md / vd.md — BA/SA/VD context"]
        I0 --> I1 --> I2 --> I3 --> I4 --> I5 --> I6 --> I7 --> I8
    end

    subgraph CONFLUENCE_RULE["Confluence pages in input/ — READ THEM, don't re-fetch"]
        C1["✅ DO: read input/TICKET/confluence/PageName.md"]
        C2["❌ DON'T: call dmtools confluence_* to re-fetch pages already in input/"]
        C3["✅ DO: read image files in input/TICKET/confluence/ — they are attachments from that page"]
    end

    subgraph ATTACH_RULE["Attachments — check before fetching via API"]
        A1["Search glob 'input/**/*.png' and 'input/**/*.jpg' — find pre-downloaded images"]
        A2["If image found locally → analyze it directly, no API call needed"]
        A3["If attachment NOT in input/ → use dmtools confluence_get_content_attachments <id>"]
        A1 --> A2
        A1 -->|not found| A3
    end

    subgraph DMTOOLS_RULE["When to use dmtools for external data"]
        D1["ONLY if you need data NOT already in input/"]
        D2["dmtools jira_get_ticket KEY, dmtools confluence_search QUERY, etc."]
        D3["See instructions/common/dmtools_cli.md for full reference"]
    end

    INPUT_ORDER --> CONFLUENCE_RULE --> ATTACH_RULE --> DMTOOLS_RULE

[5] `./agents/instructions/story_development/general_guidelines.md`

flowchart TD
    START([Story ticket ready for development]) --> READ_INPUT["⚠️ MANDATORY: Read ALL input files FIRST — see instructions/common/input_context_reading.md"]
    READ_INPUT --> PARENT["Read parent epic context if present:<br/>- input/TICKET/parent_context_ba.md — business rules<br/>- input/TICKET/parent_context_sa.md — technical design<br/>- input/TICKET/parent_context_vd.md — visual design"]
    PARENT --> ANALYZE["Analyze requirements — every acceptance criterion must be addressed"]
    ANALYZE --> ARCH["Understand existing codebase patterns, architecture, and test structure"]
    ARCH --> PRINCIPLES["Apply OOP principles: SRP, OCP, DI, Encapsulation, Composition over inheritance"]
    PRINCIPLES --> TDD["Follow TDD approach — see tdd_approach.md"]
    TDD --> TEST_LOC["Write TDD tests in the standard unit-test tree only<br/>— Flutter/Dart: test/<br/>— NEVER in testing/ (owned by test-automation agents)"]
    TEST_LOC --> IMPLEMENT["Implement source code and unit tests following existing patterns"]
    IMPLEMENT --> DOCS["Update documentation ONLY if ticket explicitly requires it"]
    DOCS --> RUN["Run all unit tests — MUST pass before finishing"]
    RUN --> PASS{Tests pass?}
    PASS -->|No| FIX["Fix failures and re-run tests"]
    FIX --> RUN
    PASS -->|Yes| GITSTATUS["Run git status and review every new/modified file"]
    GITSTATUS --> SECRETS{Sensitive or untracked non-code files present?}
    SECRETS -->|Yes| IGNORE["Add appropriate patterns to .gitignore"]
    SECRETS -->|No| SUMMARY["Write concise PR description to outputs/response.md — see output_rules.md"]
    IGNORE --> SUMMARY
    SUMMARY --> END([End — post-processing handles branch, commit and PR])

[6] `./agents/instructions/story_development/tdd_approach.md`

flowchart TD
    subgraph TDD["TDD — Test-Driven Development Workflow"]
        T0["Start with a clear understanding of the requirement"]
        T1["RED: Write a failing unit test FIRST<br/>— before any production code<br/>— test must describe the expected behavior<br/>— run it to confirm it FAILS"]
        T2["GREEN: Write minimum production code to make the test PASS<br/>— no over-engineering<br/>— simplest possible implementation"]
        T3["REFACTOR: Clean up code while keeping tests GREEN<br/>— improve naming, remove duplication<br/>— apply OOP principles<br/>— run tests after every change"]
        T4{"More requirements to implement?"}
        T5["Repeat RED-GREEN-REFACTOR for next behavior"]
        T0 --> T1 --> T2 --> T3 --> T4
        T4 -->|Yes| T5 --> T1
        T4 -->|No| DONE([All behaviors implemented with tests])
    end

    subgraph RULES["TDD Rules"]
        R1["❌ NEVER write production code without a failing test first"]
        R2["❌ NEVER write more production code than needed to pass the test"]
        R3["✅ Tests must be fast, isolated, and deterministic"]
        R4["✅ Aim for 100% unit test coverage on new and modified code"]
        R5["✅ Run the full test suite before finishing — no regressions allowed"]
    end

    TDD --> RULES

Where to write TDD tests

Write failing unit / widget tests in the project’s standard unit-test tree only:

Flutter / Dart projects → test/
Node projects → __tests__/ or test/ according to the repo convention
Python projects → tests/ or project-specific unit-test directory

Never place development TDD tests under testing/. testing/ is owned by test-automation agents (regression probes, workflow observation tests, accessibility gates, etc.). If your production changes break existing tests there, leave them untouched and mention the breakage in outputs/response.md so the test-automation agent can update them.

[7] `./agents/instructions/story_development/output_rules.md`

flowchart TD
    O1["Write outputs/response.md — concise PR description"]
    O2["Target length: under 20 lines. A reviewer should understand the change in under 30 seconds"]
    O3["Required sections:<br/>### What changed<br/>1-2 sentences describing the implementation"]
    O4["### Key decisions<br/>Bullet list of architectural or design choices"]
    O5["### How to verify<br/>Test command or verification steps"]
    O6["Optional: add a mermaid diagram inside &lt;details&gt; block summarizing the change"]
    O7["❌ NO verbose restatement of ticket requirements<br/>❌ NO water words or filler text"]
    O1 --> O2 --> O3 --> O4 --> O5 --> O6 --> O7

[8] `./agents/instructions/story_development/formatting_rules.md`

flowchart TD
    F1["outputs/response.md is a PR description — not a report or essay"]
    F2["Use bullet points and short sentences, not paragraphs"]
    F3["Technical focus: WHAT changed and WHY, not WHAT the ticket asked for"]
    F4["If including mermaid diagram: wrap in &lt;details&gt;&lt;summary&gt;Architecture&lt;/summary&gt;...&lt;/details&gt;"]

[9] `./agents/instructions/story_development/few_shots.md`

Example PR descriptions — follow this structure and brevity:

flowchart TD
    E1["### What changed<br/>Added JWT validation interceptor to protect all authenticated endpoints."]
    E2["### Key decisions<br/>- Reused existing `AuthFilter` pattern instead of introducing Spring Security<br/>- Extracted token validation into `JwtValidator` service for testability and reuse"]
    E3["### How to verify<br/>```bash<br/>./gradlew test --tests '*AuthInterceptorTest*'<br/>```"]
    E4["&lt;details&gt;&lt;summary&gt;Architecture diagram&lt;/summary&gt;<br/><br/>```mermaid<br/>flowchart TD<br/>  REQ[HTTP Request] --> INT[AuthInterceptor]<br/>  INT --> VAL[JwtValidator]<br/>  VAL -->|valid| CTL[Controller]<br/>  VAL -->|invalid| ERR[401 Response]<br/>```<br/><br/>&lt;/details&gt;"]

[10] `./agents/instructions/common/dmtools_cli.md`

DMTools CLI — External Data Access

PR Review note: Ticket/PR context is pre-loaded. Use dmtools only for additional data (e.g., parent story details, linked tickets not in input/).

Use dmtools CLI only when data is not already in input/.

flowchart TD
    NEED["Need external context?"] --> CHECK{"Already in input/?"}
    CHECK -->|Yes| READ["Read local files — NO API call"]
    CHECK -->|No| SOURCE{"Source"}

    SOURCE -->|Jira| J["dmtools jira_get_ticket KEY<br/>dmtools jira_search_by_jql JQL"]
    SOURCE -->|Confluence| C["dmtools confluence_get_page_by_url URL<br/>dmtools confluence_search QUERY"]
    SOURCE -->|ADO| A["dmtools ado_get_work_item ID<br/>dmtools ado_search_work_items QUERY"]
    SOURCE -->|GitHub| G["dmtools github_get_issue REPO NUM<br/>dmtools github_search_code QUERY"]

    J --> PARSE["Parse JSON → use in response"]
    C --> PARSE
    A --> PARSE
    G --> PARSE

    subgraph RULES["⚠️ Rules"]
        R1["Check input/ first — avoid redundant fetches"]
        R2["Handle errors gracefully — continue with available info"]
        R3["Cite sources — mention where data came from"]
    end

    PARSE --> RULES

    NOTE["Examples:<br/>dmtools jira_get_ticket PROJ-456<br/>dmtools confluence_search 'parser spec'<br/>dmtools confluence_get_page_by_url URL"] -.-> NEED

[11] `./agents/prompts/bash_tools.md`

flowchart TD
    subgraph USE["Use dmtools skill"]
        U1["Jira, Figma, Confluence, Teams, etc."]
        U2["Credentials preconfigured via environment variables"]
    end

    subgraph SAFETY["CLI command safety"]
        S1["One simple executable command at a time"]
        S2["DMTools rejects shell metacharacters"]
    end

    subgraph FORBIDDEN["NEVER USE"]
        F1["Pipes: |"]
        F2["Redirection: > < 2>/dev/null"]
        F3["Chaining: ; && ||"]
        F4["Substitution: backticks, $(), ${...}"]
    end

    subgraph EXAMPLES["Instead"]
        E1["find ... | head -20"] --> E1a["run: find ..."]
        E2["cmd1 && cmd2"] --> E2a["run: cmd1"] --> E2b["then: cmd2"]
        E3["Complex logic"] --> E3a["Write script file, run script as single command"]
    end

    subgraph CWD["Working directory discipline (persistent shell!)"]
        C1["Your Bash shell is ONE persistent session for the whole task — a cd in one command carries over to every later command, including Write/Edit"]
        C2["cd dependencies/&lt;repo&gt; to explore a dependency's source? You are now inside it for every subsequent command until you cd out"]
        C3["Forgetting to cd back before writing outputs/* silently writes to dependencies/&lt;repo&gt;/outputs/* instead of the job's own outputs/ — the write itself succeeds, so nothing looks wrong, but the file is lost"]
        C4["Before ANY Write/Edit to outputs/ (response.md, pr_review.json, pr_review_comments/*.md, etc.): run pwd first and confirm you are at the job root, not inside dependencies/"]
        C5["If unsure or already deep in a dependency checkout: cd to the ABSOLUTE job root path shown in the very first tool result of this session before writing outputs/*"]
        C6["Do NOT defensively re-cd into a directory you are already in — running cd dependencies/&lt;repo&gt; a second time while already inside it fails with No such file or directory (it looks for a nested dependencies/&lt;repo&gt;/dependencies/&lt;repo&gt;). Run pwd first if unsure; only cd once per direction change"]
        C7["For one-off commands inside a dependency checkout, prefer git -C dependencies/&lt;repo&gt; &lt;command&gt; over cd dependencies/&lt;repo&gt; then command — the -C form targets that directory without depending on or changing the shell cwd, so there is no cd bookkeeping to get wrong"]
        C8["Git global flags like --no-pager go BEFORE the subcommand: git --no-pager diff ... is correct, git diff ... --no-pager errors out (git treats the trailing flag as a positional argument)"]
    end

    USE --> SAFETY
    SAFETY --> FORBIDDEN
    SAFETY --> EXAMPLES
    SAFETY --> CWD

Agent Snapshot: story_development

Base cliPrompts

[1] Role / Plain Text

[2] ./agents/instructions/common/agent_task_preamble.md

[3] ./agents/instructions/common/coding_guidelines.md

[4] ./agents/instructions/common/input_context_reading.md

[5] ./agents/instructions/story_development/general_guidelines.md

[6] ./agents/instructions/story_development/tdd_approach.md