Skip to content

docs(agents): plan, build and review sessions per issue, and a short-output check script - #25

Merged
MendesMat merged 2 commits into
mainfrom
docs/session-workflow
Sep 28, 2026
Merged

MendesMat merged 2 commits into
mainfrom
docs/session-workflow

Conversation

@MendesMat

Copy link
Copy Markdown
Owner

What

Documents how an issue is worked on with agents after the lessons of issue #6, and adds check.ps1, a single command that formats, builds and tests with short output.

Why

Issue #6 showed three problems:

  • Cost. One long conversation carried the survey, 13 TDD cycles and the review; repeated ENDOFLINE listings and full test logs filled it, and every line is paid again on each reply.
  • Improvised decisions. Where the plan was vague, the build step filled the gap by guessing, and one guess contradicted API-12.
  • Late review. The review happened after the merge, so its fixes needed a second pull request (fix(api): complete the error mapping and test it through HTTP #23).

What changes

  • Three sessions per issue (docs/agents/workflows/implement-a-feature.md, section Sessions and new step 9):
    • plan, ending with a plan comment on the issue: decisions, new messages, and the test list with the expected result of each test;
    • build, which follows that comment instead of repeating the survey;
    • review in a new conversation, before the owner merges.
  • Owner's guide (docs/agents/trabalhando-com-agentes.md, in Portuguese): which model and effort to use in each session, what to paste to start each one, when to use pair or autonomous mode, when to switch models, and how to watch the quota.
  • check.ps1 (backend/ControlService): runs dotnet format, then the build, then the tests. It prints only problems and summaries, and keeps the whole test output when a test fails, as the evidence of a Red. It replaces the separate commands in AGENTS.md, the testing guide, the git workflow and the backend README.
  • AGENTS.md: asks for short tool output, and treats a failed approach from the approved plan as a stop point.
  • TDD workflow: commit before each pause and show it in the report.
  • Communication guide: the plan comment is part of the normal flow, so it does not need a separate confirmation.

How to test

powershell.exe -NoProfile -File backend/ControlService/check.ps1

Checked on three runs:

  • the whole solution: 137/137, exit 0;
  • a filtered run: 9/9, exit 0;
  • a throwaway failing test written with LF line endings: the endings were fixed silently, the failure was printed in full, and the exit code was 2.

The relative links of every changed document resolve.

Checklist

  • Developed test-first (ADR-0033): not applicable, documentation and a tooling script, checked by the runs above
  • dotnet test --solution ControlService.slnx passes locally
  • Documentation updated (AGENTS.md, docs/agents/, backend README)
  • Rule IDs covered or changed: none
  • User-facing messages: none

During issue #6, repeated ENDOFLINE listings and full test logs filled
the agent's context, and every line is paid again on each reply. The
script fixes the formatting first, builds quietly, and prints the whole
test output only when a test fails, as the evidence of a Red.
Records the workflow agreed after issue #6: a plan session that ends
with a plan comment on the issue (decisions and the test list with
the expected result of each test), a build session that follows it,
and a review session in a new conversation before the owner merges.
The owner's guide says which model and effort to use in each one.

AGENTS.md makes check.ps1 the default command, asks for short tool
output, and treats a failed planned approach as a stop point. The TDD
workflow commits before each pause.
@MendesMat
MendesMat enabled auto-merge (squash) September 28, 2026 05:40
@MendesMat
MendesMat disabled auto-merge September 28, 2026 05:40
@MendesMat
MendesMat merged commit 8754585 into main Sep 28, 2026
5 checks passed
@MendesMat
MendesMat deleted the docs/session-workflow branch September 28, 2026 05:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant