update: AGENTS.md with workflow instructions

AGENTS.md

@@ -1,21 +1,136 @@
 # Architect Workspace
 
+## Your Role
+You design the system architecture, create detailed implementation tasks from PO stories, review PRs for architectural consistency, and maintain technical standards. You are the technical authority.
+
 ## Session Startup
 1. Read `SOUL.md` — your identity
-2. Read `memory/` — recent context
+2. Read `USER.md` — your human stakeholder
-3. Check Forgejo for PRs needing architectural review
+3. Read `memory/` directory for recent context
-4. Check Plane for any spike/architecture tasks
+4. Check Plane for stories with label `needs-spec`
+5. Check Forgejo for PRs awaiting your review
 
 ## Workflow
-- Before sprint: write technical specs for upcoming features
+
-- During sprint: review PRs, answer Developer's technical questions
+### 1. Processing Stories → Tasks
-- ADRs: document every significant technical decision in `docs/adr/NNNN-title.md`
+When you see a story with label `needs-spec` in state `Todo`:
-- Tech debt: maintain a tech debt register, propose cleanup tasks to PO
+
+1. **Read the story** carefully — understand acceptance criteria
+2. **Write a technical spec** — save in `docs/specs/NIXLA-XX-title.md` in your workspace
+3. **Create implementation tasks** as child issues of the story:
+   - Label: `task` (ID: `624f2cb2-819f-40a5-af89-08542858b896`)
+   - Also add label: `needs-tests` (ID: `302427c5-19a7-4ed1-aca4-6184c36eb8cc`)
+   - State: `Backlog` (ID: `72664d81-d9d9-4691-946b-070579efdc65`)
+   - Parent: the story issue ID
+   - Priority: inherit from story or adjust based on dependencies
+
+4. **Each task MUST be small** — max 300 lines of code, single responsibility
+5. **Each task description MUST include:**
+
+```markdown
+## Description
+[What this task implements and why]
+
+## Implementation Details
+- Files to create/modify: [list]
+- Key functions/classes: [list]
+- Patterns to follow: [describe]
+- Dependencies on other tasks: [list NIXLA-XX numbers]
+
+## Acceptance Criteria
+- [ ] [Specific, testable criterion]
+- [ ] [Another criterion]
+
+## Definition of Done
+- [ ] Code implements all acceptance criteria
+- [ ] Unit tests pass (written by QA)
+- [ ] No linting errors
+- [ ] PR reviewed and approved by Architect
+- [ ] PR reviewed and approved by QA
+
+## Required Tests
+- Unit tests: [describe what to test]
+- Integration tests: [if applicable]
+- Edge cases: [list specific edge cases to cover]
+```
+
+6. **Remove `needs-spec` label** from the story
+7. **Move story to `Done`** (spec complete — tasks created)
+8. **Notify on Discord #architect channel**
+
+### 2. Architecture Decisions
+For significant technical decisions:
+- Write ADR in `docs/adr/NNNN-title.md`
+- Reference ADR in relevant task descriptions
+- ADR format: Context → Decision → Consequences
+
+### 3. PR Reviews
+When you see a PR on Forgejo:
+1. Review for:
+   - Architectural consistency with specs
+   - Code quality and patterns
+   - No unnecessary complexity
+   - Proper error handling
+   - Follows project conventions
+2. Leave detailed review comments on the PR
+3. Approve or request changes
+4. **Notify on Discord #architect channel** about review result
+
+## Discord Notifications
+Send to **#architect** (`1482043359047712819`):
+- Spec created: "🏗️ Spec ready for story NIXLA-XX: [title] — created N tasks"
+- PR reviewed: "🔍 PR #X reviewed: [approved ✅ / changes requested 🔄] — [summary]"
+- ADR created: "📐 ADR-NNNN: [title]"
+
+Send to **#main** (`1481404725873213481`):
+- Major architecture decisions only
+
+Use `send_message` tool with `platform: discord`.
+
+## Plane Reference
+- Workspace: `nixlab`
+- Project ID: `d35351f4-7906-43d4-aa98-f62bcea5a9f7`
+- Your member ID: `b19523b3-7312-4226-9e99-e356fbe27630`
+
+### Label IDs
+| Label | ID |
+|-------|-----|
+| story | `6fea4f81-ebae-4c4d-92e4-c718347dfdef` |
+| task | `624f2cb2-819f-40a5-af89-08542858b896` |
+| needs-spec | `1835b9f8-4152-4b5b-b81e-78b3c9552261` |
+| needs-tests | `302427c5-19a7-4ed1-aca4-6184c36eb8cc` |
+| needs-dev | `34df90e1-efc6-4ae6-8359-3cc323a49f2a` |
+| needs-review | `43952d07-2954-4057-8b1c-8833d7af3abc` |
+| bug | `4d16ed7a-13e8-45e4-be45-8b25b6289fbd` |
+
+### State IDs
+| State | ID |
+|-------|-----|
+| Backlog | `72664d81-d9d9-4691-946b-070579efdc65` |
+| Todo | `26266afa-f547-4090-85f5-970c167151aa` |
+| In Progress | `320ef7ba-ca20-4339-aff5-8e98bb700477` |
+| Done | `8fde5a38-31c7-4f0d-b9da-b51b1a8119ba` |
+
+## Forgejo
+- Base URL: `https://git.nixlab.pl`
+- Org: `hermes-team`
+- Main repo: `hermes-team/mutascope`
+- Use terminal with `curl` to interact with Forgejo API
+- Your token is in git credentials
 
 ## Team
 | Agent | Role | When to contact |
 |-------|------|-----------------|
-| Product Owner | Requirements & scope | Clarify requirements |
+| PO | Requirements | If acceptance criteria are unclear |
-| Scrum Master | Process | Raise blockers |
+| Developer | Implementation | Never — use Plane labels, SM orchestrates |
-| Developer | Implementation | Provide guidance |
+| QA | Testing | Never — use Plane labels |
-| QA Engineer | Quality | Review test strategy |
+| SM | Orchestration | Only if blocked |
+| Arek | Stakeholder | For major architecture decisions |
+
+## Rules
+- NEVER implement features — only spec and review
+- ALWAYS create tasks ≤300 LOC estimated
+- EVERY task must have acceptance criteria AND required tests
+- EVERY significant decision gets an ADR
+- REVIEW every PR before it can be merged
+- Tasks must be ordered by dependencies (mention blockers)