Specflux Coding

SpecFlux Coding Workflow

When implementing code in a SpecFlux project, you MUST follow this workflow exactly. No exceptions.

CRITICAL: Pre-Flight Checks

BEFORE writing any code, you MUST complete these checks. If any fail, STOP and inform the user.

1. Verify API Access

# Check environment variables are set
echo $SPECFLUX_API_URL   # Must not be empty
echo $SPECFLUX_API_KEY   # Must not be empty, should start with "sfx_"

# Test API connectivity with authentication
curl -s -w "%{http_code}" -o /dev/null \
  -H "Authorization: Bearer $SPECFLUX_API_KEY" \
  "$SPECFLUX_API_URL/api/projects"

If SPECFLUX_API_URL or SPECFLUX_API_KEY is not set, or API is unreachable:

• STOP immediately
• Inform user: "Cannot proceed - SpecFlux API is not accessible. Please ensure SPECFLUX_API_URL and SPECFLUX_API_KEY are set and the API is running."
• Do NOT proceed with implementation

2. Verify Task Exists

# Fetch task details
GET /api/projects/{projectRef}/tasks/{taskRef}

If task not found or API returns error:

• STOP immediately
• Inform user of the error
• Do NOT proceed with implementation

3. Mark Task IN_PROGRESS

PATCH /api/projects/{projectRef}/tasks/{taskRef}
{"status": "IN_PROGRESS"}

If status update fails:

• STOP immediately
• Inform user: "Cannot update task status. Please check API access."
• Do NOT proceed with implementation

MANDATORY Workflow

You MUST follow these steps IN ORDER. Skipping steps is NOT allowed.

┌─────────────────────────────────────────────────────────────────┐
│                    MANDATORY WORKFLOW                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  BEFORE CODING (all steps required):                             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ □ 1. Verify API access (STOP if fails)                   │   │
│  │ □ 2. Fetch task details from API                         │   │
│  │ □ 3. Mark task IN_PROGRESS via API                       │   │
│  │ □ 4. Read acceptance criteria from API                   │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  DURING CODING:                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ □ 5. Write tests for each acceptance criterion           │   │
│  │ □ 6. Implement until ALL tests pass                      │   │
│  │ □ 7. Run full test suite                                 │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  AFTER CODING (all steps required):                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ □ 8. Mark each acceptance criterion as met via API       │   │
│  │ □ 9. Commit with task reference: "TASK-REF: description" │   │
│  │ □ 10. Mark task COMPLETED via API                        │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  AFTER ALL TASKS IN EPIC:                                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ □ 11. Mark epic COMPLETED via API                        │   │
│  │ □ 12. Create PR with epic reference                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Step-by-Step Details

Step 1-3: Pre-Flight (MANDATORY)

# 1. Check environment variables are set
echo $SPECFLUX_API_URL  # Must not be empty
echo $SPECFLUX_API_KEY  # Must not be empty, should start with "sfx_"

# 2. Fetch task
curl -s -H "Authorization: Bearer $SPECFLUX_API_KEY" \
  "$SPECFLUX_API_URL/api/projects/{projectRef}/tasks/{taskRef}"

# 3. Mark IN_PROGRESS
curl -s -X PATCH -H "Authorization: Bearer $SPECFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  "$SPECFLUX_API_URL/api/projects/{projectRef}/tasks/{taskRef}" \
  -d '{"status": "IN_PROGRESS"}'

Step 4: Read Acceptance Criteria

curl -s -H "Authorization: Bearer $SPECFLUX_API_KEY" \
  "$SPECFLUX_API_URL/api/projects/{projectRef}/tasks/{taskRef}/acceptance-criteria"

Steps 5-7: Test-First Development

1. Write tests FIRST - Each acceptance criterion needs at least one test
2. Tests should fail initially - No implementation yet
3. Implement until ALL tests pass
4. Run full test suite - Ensure no regressions

Test Requirements

1. Acceptance Criteria Tests (REQUIRED)

Every acceptance criterion MUST have at least one corresponding test that verifies it.

Criterion: "Users can log in with email/password"
    → Test: testLoginWithValidCredentialsReturnsToken()
    → Test: testLoginWithInvalidPasswordReturns401()

Criterion: "API returns paginated results"
    → Test: testGetUsersReturnsPaginatedResponse()
    → Test: testPaginationCursorNavigatesCorrectly()

Rules:

• Test must fail before implementation, pass after
• Mark criterion complete via API only when test passes
• One criterion may require multiple tests for complete coverage

2. Proactive Testing for Critical Components

Beyond acceptance criteria, add tests for:

Guideline: More tests for risky/complex code. Use judgment - three lines of trivial code don't need three tests.

3. Manual Review Criteria

Criteria tagged with [manual] are skipped during automated verification:

Acceptance Criteria:
- User can log in with email/password          → test required, auto-verified
- Login form shows validation errors           → test required, auto-verified
- [manual] UI matches design mockup            → skipped, flagged for review
- [manual] Copy is reviewed by legal           → skipped, flagged for review

Handling [manual] criteria:

• Do NOT write automated tests for these
• Do NOT block task completion on these
• DO report them in task completion summary
• DO flag them for human review before release

Example completion summary:

✅ Task SPEC-42 Complete

Automated Criteria (verified):
- [✓] Users can log in with email/password
- [✓] Login form shows validation errors

Manual Review Required:
- [ ] UI matches design mockup
- [ ] Copy is reviewed by legal

Step 8: Mark Criteria Met

For EACH acceptance criterion:

curl -s -X PUT -H "Authorization: Bearer $SPECFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  "$SPECFLUX_API_URL/api/projects/{projectRef}/tasks/{taskRef}/acceptance-criteria/{id}" \
  -d '{"isMet": true}'

Step 9: Commit

git add .
git commit -m "TASK-REF: brief description

Co-Authored-By: Claude <noreply@anthropic.com>"

Step 10: Mark Task COMPLETED

curl -s -X PATCH -H "Authorization: Bearer $SPECFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  "$SPECFLUX_API_URL/api/projects/{projectRef}/tasks/{taskRef}" \
  -d '{"status": "COMPLETED"}'

If this fails, you MUST retry or inform the user. Do NOT leave tasks in IN_PROGRESS state.

Steps 11-12: Epic Completion

After ALL tasks in an epic are done:

# Mark epic completed
curl -s -X PATCH -H "Authorization: Bearer $SPECFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  "$SPECFLUX_API_URL/api/projects/{projectRef}/epics/{epicRef}" \
  -d '{"status": "COMPLETED"}'

# Create PR
gh pr create --title "EPIC-REF: Epic title" --body "..."

MUST NOT Rules

You MUST NOT:

• Start coding without marking task IN_PROGRESS
• Skip writing tests for acceptance criteria
• Commit without all tests passing
• Leave task in IN_PROGRESS after completing work
• Forget to mark epic COMPLETED when all tasks are done
• Create PR without updating epic status
• Proceed with implementation if API calls fail

Error Handling

API Unavailable

STOP. Inform user:
"SpecFlux API is not accessible. Please ensure:
1. SPECFLUX_API_URL environment variable is set
2. SPECFLUX_API_KEY environment variable is set (should start with 'sfx_')
3. API server is running
4. Network connectivity is available"

Status Update Fails

RETRY once. If still fails:
"Failed to update task/epic status via API. Please manually update:
- Task {taskRef} → {status}
- Epic {epicRef} → {status} (if applicable)"

Tests Failing

Do NOT commit. Do NOT mark task complete.
Continue debugging until ALL tests pass.

API Quick Reference

# Task operations
GET    /api/projects/{projectRef}/tasks/{taskRef}
PATCH  /api/projects/{projectRef}/tasks/{taskRef}  {"status": "IN_PROGRESS|COMPLETED|BLOCKED"}

# Acceptance criteria
GET    /api/projects/{projectRef}/tasks/{taskRef}/acceptance-criteria
PUT    /api/projects/{projectRef}/tasks/{taskRef}/acceptance-criteria/{id}  {"isMet": true}

# Epic operations
GET    /api/projects/{projectRef}/epics/{epicRef}
PATCH  /api/projects/{projectRef}/epics/{epicRef}  {"status": "IN_PROGRESS|COMPLETED"}

Verification Checklist

Before saying "task complete", verify:

• Task status is COMPLETED in API (not just locally)
• All acceptance criteria marked as met in API
• Commit exists with task reference
• If last task in epic: epic status is COMPLETED
• If last task in epic: PR has been created or offered