Task Implementation

Implement development tasks following engineering standards with quality gates and progress tracking.

Related References

• •references/gate-checklist.md - Detailed gate validation steps

1. Inputs

Required

• •Task ID(s): One or more task IDs to implement (e.g., CTI-01, SP-02,SP-03)

Auto-loaded

These files are automatically read at the start of implementation:

1. •docs/engineering/STACK.md - Tech stack and available scripts
2. •docs/engineering/CODE_STANDARDS.md - Development philosophy and quality standards
3. •docs/engineering/WORKFLOW.md - Git workflow and commit guidelines

Task Definition

Read the task definition from docs/tasks/<epic-slug>.md:

• •Description and acceptance criteria
• •Files to create/modify
• •Technical notes
• •Testing requirements

Optional Context (read when needed)

• •docs/PRD.md - Product requirements for business context
• •docs/architecture/*.md - Architecture decisions and patterns
• •docs/use-cases/*.md - User scenarios and edge cases

2. Pre-Implementation Setup

Step 1: Understand the Task

Before writing code:

1. •Read the full task definition from docs/tasks/
2. •Understand all acceptance criteria
3. •Identify dependencies on other tasks
4. •Check current progress in docs/progress/<epic-slug>.md

If task has dependencies marked as TODO or IN_PROGRESS:

⚠️ Task [ID] depends on [DEP-ID] which is not complete. Do you want to implement the dependency first?

Step 2: Create Semantic Branch

Create a branch following naming convention:

# Single task
git checkout -b feat/<epic-slug>-<task-description>

# Examples
git checkout -b feat/cti-tracing-interface
git checkout -b fix/sp-session-restore
git checkout -b refactor/jp-job-middleware

Branch types from WORKFLOW.md:

• •feat/ - New feature
• •fix/ - Bug fix
• •refactor/ - Code refactoring
• •chore/ - Tooling, config
• •docs/ - Documentation only
• •test/ - Test additions

Step 3: Update Progress Status (CRITICAL)

This step is MANDATORY and must happen BEFORE writing any code.

Update docs/progress/<epic-slug>.md immediately:

### [TASK-ID] Task Name

**Status**: `IN_PROGRESS`
**Started**: YYYY-MM-DD
**Notes**: Starting implementation

⚠️ DO NOT skip or defer this step. Progress tracking provides:

• •Visibility into current work
• •Recovery point if implementation fails
• •Accurate timestamps for reporting

3. Implementation Workflow

Development Loop

For each acceptance criterion:

1. •Implement - Write code following CODE_STANDARDS.md
2. •Test - Run tests if applicable
3. •Commit - Semantic commit for the change

Semantic Commits

Follow commit format from WORKFLOW.md:

<type>(<scope>): <short description>

[optional body]

Types: feat, fix, refactor, chore, docs, test, style, perf

Commit by functional activity, not by file.

# ✅ Good
git commit -m "feat(tracing): add correlation ID interface"

# ❌ Bad
git commit -m "update TracingInterface.php"

Code Quality Standards

From CODE_STANDARDS.md:

• •No DDD - No over-engineering
• •Pragmatic SOLID - Apply for clarity, not layers
• •Testable - Business logic is unit-testable
• •Extensible - Easy to add features

4. Quality Gates

All gates MUST pass before completing a task.

Gate 1: Code Quality (Lint)

composer lint

This runs Pint (formatting), Rector (refactoring), and PHPStan (analysis).

If lint fails:

1. •Fix reported issues
2. •Re-run composer lint
3. •Commit fixes: style: fix lint issues

Gate 2: Tests

Check the task definition for testing requirements:

**Testing**:

- [ ] Unit tests for ClassName
- [ ] Feature tests for behavior

If tests are required by task:

1. •

   Invoke generate-test skill:

   Gere testes para os arquivos implementados nesta task

2. •

   generate-test will:

   • •Analyze implemented code
   • •Create appropriate test files
   • •Run tests
   • •Report results
3. •

   Tests MUST pass before proceeding

4. •

   Commit tests: test(scope): add tests for [feature]

If tests are NOT required:

composer test

• •Existing tests must still pass
• •Consider invoking generate-test for complex logic

If tests fail:

1. •Analyze failure (test wrong or code wrong?)
2. •Fix appropriately
3. •Re-run until passing

See references/gate-checklist.md for detailed test gate steps.

Gate 3: Security Analysis

Invoke security-analyst skill on files created/modified:

Analise a segurança dos arquivos modificados nesta task

If CRITICAL or HIGH findings:

• •Must fix before completing task
• •Commit fixes: fix(security): [description]

If MEDIUM/LOW/INFO findings:

• •Inform user, proceed with their decision

See references/gate-checklist.md for detailed validation steps.

5. Task Completion

Update Progress Tracking

When all acceptance criteria are met and gates pass:

Step 1: Update Epic Progress File

Update docs/progress/<epic-slug>.md:

### [TASK-ID] Task Name

**Status**: `DONE`
**Started**: YYYY-MM-DD
**Completed**: YYYY-MM-DD
**Commits**:

- `abc1234` feat(scope): description
- `def5678` test(scope): add tests
  **Notes**: Implementation details or decisions made

Step 2: Update Progress README (MANDATORY)

Update docs/progress/README.md with:

1. •Epic Progress table: Update counts (TODO → Done) and percentage
2. •Recent Completions table: Add completed task at the top
3. •Current Focus: Update if epic changed or task in progress changed
4. •Total row: Recalculate totals across all epics
5. •Last Updated date: Update to current date

⚠️ The README.md is a dashboard derived from epic progress files. It MUST be updated after every task completion to maintain accuracy.

Update Related Documentation

If implementation affects documentation:

• •Update relevant docs/architecture/*.md
• •Update README.md if public API changed
• •Update config file comments if new options added

6. Pull Request

Ask Before Opening

Always ask the user:

✅ Task [ID] concluída com sucesso. Deseja que eu abra um Pull Request?

If User Confirms

Create PR with semantic title and detailed description:

Title Format:

<type>: <short description>

Examples:
feat: Add correlation ID tracing interface
fix: Preserve context in queued jobs

Description Template:

## What

[Brief description of changes]

## Why

[Motivation and context]
[Reference to task: Implements CTI-01 from docs/tasks/core-tracing-infrastructure.md]

## How

[Technical approach and key decisions]

## Acceptance Criteria

- [x] AC-1: [Description]
- [x] AC-2: [Description]
- [x] AC-3: [Description]

## Quality Gates

- [x] `composer lint` passes
- [x] `composer test` passes
- [x] Security analysis: [PASS / PASS WITH WARNINGS]

## Files Changed

- `src/Path/To/File.php` - [What changed]
- `config/file.php` - [What changed]

7. Error Handling

If Gate Fails

1. •Report the failure clearly
2. •Propose a fix
3. •Ask user how to proceed:
   • •Fix and retry
   • •Skip with justification
   • •Abort task

If Task Cannot Be Completed

Update progress with BLOCKED or FAILED:

### [TASK-ID] Task Name

**Status**: `BLOCKED`
**Blocker**: [Description of what's blocking]
**Notes**: [Context and potential solutions]

8. Multi-Task Implementation

When implementing multiple tasks together:

1. •Evaluate dependencies - Order tasks by dependency
2. •Single branch - Use branch for the epic: feat/<epic-slug>
3. •Separate commits - One commit per task completion
4. •Single PR - Batch related tasks in one PR

Progress Tracking (CRITICAL)

For each task in the batch, follow this exact sequence:

1. •

   BEFORE starting task N:

   • •Update docs/progress/<epic-slug>.md with IN_PROGRESS status
   • •Update docs/progress/README.md table and totals
   • •This must happen BEFORE writing any code for that task
2. •

   AFTER completing task N:

   • •Update progress with DONE status and commit hash
   • •Update docs/progress/README.md table and totals
   • •Update docs/progress/README.md progress status, decisions made, and next steps
   • •Commit the progress update

DO NOT batch progress updates. Each task's progress must be updated individually as you work through them.

Example sequence for tasks CTI-01, CTI-02, CTI-03:

1. Update CTI-01 → IN_PROGRESS
2. Implement CTI-01
3. Update CTI-01 → DONE
4. Update CTI-02 → IN_PROGRESS  ← happens immediately after CTI-01 done
5. Implement CTI-02
6. Update CTI-02 → DONE
7. Update CTI-03 → IN_PROGRESS
8. Implement CTI-03
9. Update CTI-03 → DONE

This ensures:

• •Visibility into which task is being worked on
• •Recovery point if implementation fails mid-epic
• •Accurate timestamps for start/completion

9. Triggering Phrases

• •"Implemente a task CTI-01"
• •"Desenvolva SP-02 e SP-03"
• •"Implement task JP-01"
• •"Code the authentication task"
• •"Comece o desenvolvimento de HCI-01"

10. Language Rules

• •Code: English (variables, functions, comments)
• •Commits: English
• •PR descriptions: English
• •Conversation with user: Portuguese (pt-BR)
• •Progress notes: English

Completion Criteria

Task implementation is complete when:

1. •✅ All acceptance criteria are met
2. •✅ composer lint passes
3. •✅ composer test passes (or tests written if required)
4. •✅ Security analysis shows no CRITICAL/HIGH issues
5. •✅ Semantic commits made for each change
6. •✅ Epic progress file updated (docs/progress/<epic-slug>.md)
7. •✅ Progress README updated (docs/progress/README.md)
8. •✅ User asked about Pull Request