| name | start-working |
| description | Autonomously execute ALL tasks from the backlog until complete. Runs in a continuous loop - picks task, implements via subagent, moves to done, repeats. No user prompts between tasks. Follows task-board workflow (backlog → in-progress → done). |
Start Working Skill
This skill autonomously executes ALL tasks from the task board until the backlog is empty. It runs in a continuous loop without stopping between tasks.
Task Board Flow: .task-board/backlog/ → .task-board/in-progress/ → .task-board/done/
🚨 AUTONOMOUS MODE: This skill does NOT stop between tasks. It continues until all tasks are complete or a critical blocker occurs.
🚨 SIX CRITICAL RULES 🚨
1. USE THE TASK BOARD SYSTEM
ALL work flows through .task-board/ - this is non-negotiable.
- Tasks live in:
backlog/ → in-progress/ → done/
PLANNING-BOARD.md is the source of truth for priorities- NEVER work on something not tracked in the task board
- Update task files with progress as you work
Why: The task board ensures organized, trackable, sequential work with clear accountability.
2. NEVER USE GIT COMMANDS
ABSOLUTELY NO git commands - not by the main agent, not by subagents.
- ❌
git add, git commit, git push, git pull, git checkout, git branch, etc.
- ❌
git status, git diff, git log (even read-only commands)
- ❌ Any command starting with
git
Why: The user handles all git operations manually. This prevents accidental commits, branch switches, or repository state changes.
If user requests git operations: Politely decline and explain that git commands are disabled for this workflow.
3. USE SUBAGENTS WITH HAIKU BY DEFAULT
Each task MUST be executed using the Task tool with a subagent:
- Default model:
haiku - fast and efficient for most tasks
- Use
sonnet only for: D3.js visualizations, complex business logic, architectural decisions
- ALWAYS include CLAUDE.md context in subagent prompts - reference project patterns, conventions, and tech stack
4. TASKS ARE DONE IN ORDER
Tasks are numbered for dependency reasons. Execute them sequentially, in order:
- Pick task 071 → Complete → Pick task 072 → Complete → Pick task 073...
- NEVER skip ahead unless user explicitly requests it
- NEVER run tasks in parallel
5. PLAYWRIGHT CLI FOR FRONTEND VERIFICATION
Every frontend task MUST be verified with Playwright CLI before marking complete:
node scripts/playwright-verify.js <url> [screenshot-name]
The script will:
- Navigate to the page
- Wait for content to load
- Capture console errors
- Take a screenshot
- Output verification results
Frontend tasks without Playwright verification are INCOMPLETE.
6. ALWAYS PREFER TO USE TOOLS OVER BASH OR CLI!!!
Subagents MUST use built-in tools instead of bash equivalents. This is non-negotiable.
| ❌ NEVER USE | ✅ ALWAYS USE |
|---|
cat, head, tail | Read tool |
echo >, cat <<EOF | Write tool |
sed, awk | Edit tool |
find, ls (for search) | Glob tool |
grep, rg | Grep tool |
Why: Built-in tools are optimized, safer, and provide better output for Claude Code.
Example violations to watch for:
cat /path/to/file.ts
grep -r "pattern" src/
find . -name "*.tsx"
echo "content" > file.ts
Read tool: file_path="/path/to/file.ts"
Grep tool: pattern="pattern", path="src/"
Glob tool: pattern="**/*.tsx"
Write tool: file_path="file.ts", content="content"
Subagent prompts MUST include this reminder.
🚨 TWO ABSOLUTE RULES 🚨
- ALL WORK THROUGH TASK BOARD - Tasks come from
.task-board/, progress tracked in task files, never work outside the system
- NO GIT COMMANDS - Never run ANY git commands. User handles all version control manually.
When to Use This Skill
Use this skill when the user requests:
- "Start working on the next task"
- "Continue work" or "Keep going"
- "Pick up the next priority"
- "Work on the planning board items"
- "Start implementing" or "Begin development"
- Any request to begin implementation work
Workflow Overview
This skill follows a 10-step workflow that moves tasks through the lifecycle:
.task-board/backlog/ → .task-board/in-progress/ → .task-board/done/
With continuous updates to PLANNING-BOARD.md throughout the process.
The 10-Step Workflow
Step 1: Check Current Priorities
Read .task-board/PLANNING-BOARD.md to see what's next.
If PLANNING-BOARD is empty: Ask the user if they want to add priorities from the backlog first.
Example response:
The PLANNING-BOARD is currently empty. Would you like me to:
1. Add the top 3-5 priorities from backlog to the planning board?
2. Wait for you to manually select priorities?
3. Review the entire backlog and make recommendations?
Step 2: Select Top Priority
Pick the first item from the planning board (unless blocked or user specifies otherwise).
Decision criteria:
- Is it blocked by dependencies?
- Are all prerequisites met (check "Related Plans" section)?
- Is the scope clear and actionable?
- Are there any unresolved questions in the plan?
If the top priority is blocked, move to the next unblocked item.
Blocking examples:
- Task
006-FEATURE-user-api-endpoints.md is blocked if 001-FEATURE-backend-express-server.md is not done
- Task
009-FEATURE-portfolio-dashboard.md is blocked if 008-FEATURE-portfolio-api-endpoints.md is not done
Step 3: Move to In-Progress
Move the task file from .task-board/backlog/ to .task-board/in-progress/.
Example:
Move: .task-board/backlog/001-FEATURE-backend-express-server.md
To: .task-board/in-progress/001-FEATURE-backend-express-server.md
Important: Limit in-progress work to 1-2 tasks maximum. If in-progress folder already has tasks, ask user if they want to finish those first.
Step 4: Read the Task File
Thoroughly understand the task plan:
- Context & Motivation: Why is this work needed?
- Current State: What exists today?
- Desired Outcome: What success looks like
- Acceptance Criteria: Specific, testable requirements (checkboxes) - 🚨 MUST be checked off as completed
- Technical Approach: Implementation steps and architecture decisions
- Dependencies: What must be completed first
- Risks: Potential issues and mitigations
- Code References: Relevant patterns and examples
Step 5: Clarify Uncertainties (Critical)
STOP and ask the user follow-up questions if:
- The task description is unclear or ambiguous
- Multiple implementation approaches are possible
- There are technical uncertainties about the approach
- The scope seems too large or ill-defined
- Priority conflicts exist
- Dependencies are unclear
- Norwegian localization requirements are ambiguous
Only proceed to Step 6 after all uncertainties are resolved.
Example questions:
- "Should the portfolio dashboard show all snapshots or just the last 12 months?"
- "For error handling, should we show toast notifications or inline errors?"
- "The plan mentions 'optional D3.js chart' - should I implement this or skip it for MVP?"
Step 6: Assess Complexity
Evaluate if the task is appropriately sized:
If task is too complex:
- Break it down into smaller, focused sub-tasks
- Create new task files in
backlog/ for each sub-task (continue numbering sequence)
- Update
PLANNING-BOARD.md with the new breakdown
- Select the first sub-task to work on
Complexity indicators for finans project:
- Affects both frontend AND backend (consider splitting)
- Requires changes across more than 3 workspaces (frontend/backend/components)
- Estimated effort > 1 week
- Multiple new dependencies or integrations (CosmosDB + API + UI)
Example breakdown:
Original: 009-FEATURE-portfolio-dashboard.md (too complex)
Break into:
- 009a-FEATURE-portfolio-api-integration.md (fetch snapshots)
- 009b-FEATURE-net-worth-chart.md (D3.js chart only)
- 009c-FEATURE-account-table.md (account breakdown table)
Step 7: Add Implementation Plan
Update the task file with a detailed Implementation Plan section.
The plan file already has "Implementation Plan" as a placeholder section. Fill it in with:
## Implementation Plan
**Phase 1: Backend Setup** (if applicable)
- [ ] Create Express routes in `/backend/src/routes/`
- [ ] Implement controllers in `/backend/src/controllers/`
- [ ] Add validation in `/backend/src/validators/`
- [ ] Set up CosmosDB service methods
- [ ] Test with Postman/curl
**Phase 2: Frontend Implementation** (if applicable)
- [ ] Create feature folder in `/frontend/src/features/[feature-name]/`
- [ ] Implement components (React + TypeScript)
- [ ] Add TanStack Query hooks for API calls
- [ ] Set up Zustand store if needed (client state)
- [ ] Apply BeerCSS styling
- [ ] Add Norwegian text and formatting
**Phase 3: Testing**
- [ ] Manual testing in dev environment
- [ ] Verify all acceptance criteria met
- [ ] Test Norwegian number/date formatting
- [ ] Test error cases
**Phase 4: Verification**
- [ ] Frontend builds: `pnpm --filter frontend build`
- [ ] Backend builds: `pnpm --filter backend build`
- [ ] TypeScript type-check passes
- [ ] ESLint passes
- [ ] All acceptance criteria checked off
**Files to create/modify**:
- `/backend/src/routes/userRoutes.ts` (new)
- `/backend/src/controllers/userController.ts` (new)
- `/frontend/src/features/auth/LoginPage.tsx` (new)
- `/frontend/src/shared/api/client.ts` (modify)
**Dependencies**:
- Requires `.env` files configured
- Requires CosmosDB Emulator running (run `emulator.bat`)
**Estimated total time**: 2-3 days
Step 8: Update Planning Board
Mark the task as "In Progress" in PLANNING-BOARD.md with status notes.
Update format:
## Top Priorities
### 1. Backend Express Server Setup (Effort: Medium - 2-3 days) - IN PROGRESS ⚙️
**File**: `in-progress/001-FEATURE-backend-express-server.md`
**Why Now**: Foundation for all API development
**Status**: Phase 1 complete - setting up middleware
**Progress**: 3/12 acceptance criteria met
**Started**: 2025-11-28
Step 9: Implement the Solution
Follow the finans project architecture patterns and implementation workflow:
Development Environment Setup
Start development servers (if not already running):
pnpm --filter backend dev
pnpm --filter frontend dev
pnpm dev
CosmosDB Emulator (if working with database):
.\emulator.bat
Architecture Patterns to Follow
Backend (Express + TypeScript + CosmosDB):
- Folder structure: Follow vertical organization
- Routes in
/backend/src/routes/
- Controllers in
/backend/src/controllers/
- Services in
/backend/src/services/ (CosmosDB access)
- Validation in
/backend/src/validators/
- Middleware in
/backend/src/middleware/
- Error handling: Use custom error classes, global error handler
- Logging: Winston logger for structured logging
- Validation: Two-layer (input validation + business validation)
- API format:
- Success:
{ data: {...}, success: true }
- Error:
{ error: { message, code, details }, success: false }
Frontend (React 18 + Vite + TanStack Query + Zustand):
- Folder structure: Vertical slicing by feature
- Features in
/frontend/src/features/[feature-name]/
- Shared components in
/frontend/src/shared/components/
- Shared hooks in
/frontend/src/shared/hooks/
- Stores in
/frontend/src/stores/ (Zustand)
- State management:
- TanStack Query: All server state (API calls)
- Zustand: Client state (UI preferences, local state)
- React Context: Auth state only
- Components: Functional components with TypeScript
- Styling: Nordic Minimal CSS + Material UI icons
- Forms: React Hook Form + Zod validation
- Norwegian: All UI text in Norwegian, use format utilities from
shared/utils/
Norwegian Localization (CRITICAL):
- Numbers:
formatCurrency(123456.78) → "123 456,78 kr"
- Dates:
formatDate(new Date()) → "28.11.2025"
- Import utilities:
import { formatCurrency, formatNumber, parseNumber } from '@/shared/utils/numberFormat';
import { formatDate, parseDate } from '@/shared/utils/dateFormat';
Component Library (/components):
- Shared components bundled into frontend (not published to npm)
- Import:
import { Button, Card } from '@finans/components'
- Storybook for documentation (future)
Implementation Workflow
-
Read the Technical Approach section in the task file thoroughly
-
Follow the phased approach from Implementation Plan:
- Complete Phase 1 before moving to Phase 2
- Check off tasks as you complete them
- Update Progress Log frequently
-
Code incrementally:
- Create/modify one file at a time
- Test each change before moving to next
- Keep TypeScript compilation clean (no errors)
-
Follow existing patterns:
- Check "Code References" section in task file
- Look for similar implementations in codebase
- Maintain consistency with existing code
-
Test continuously:
- Manual testing after each change
- Verify acceptance criteria as you go
- Test Norwegian formatting with real data
Real-Time Progress Tracking
Update the task file's Progress Log frequently (every 30-60 minutes):
## Progress Log
- 2025-11-28 14:00 - Started implementation, reviewed task plan
- 2025-11-28 14:30 - Created Express app in /backend/src/index.ts
- 2025-11-28 15:00 - Added Winston logger configuration
- 2025-11-28 15:30 - Implemented error handler middleware
- 2025-11-28 16:00 - Tested health endpoint - working ✓
- 2025-11-28 16:30 - Added rate limiting middleware
Update PLANNING-BOARD.md as phases complete:
**Status**: Phase 2 complete - frontend components built
**Progress**: 8/12 acceptance criteria met
Testing Guidelines
Frontend testing:
- Manual testing in browser (http://localhost:5173)
- Check browser console for errors
- Test responsive design (mobile/desktop)
- Verify Norwegian formatting
- Test all user interactions
- Future: Playwright E2E tests (see task 017)
Backend testing:
- Test with Postman or curl
- Verify response format
- Test error cases (400, 401, 404, 500)
- Check Winston logs
- NOTE: No unit tests - E2E only per CLAUDE.md
Playwright CLI Visual Verification - MANDATORY FOR FRONTEND
🚨 CRITICAL: Every frontend task MUST be verified using Playwright CLI before marking complete.
This is NOT optional. Frontend tasks are NOT complete until visually verified.
Design drafts location: .docs/design-drafts/
draft-1-nordic-minimal.html - Dashboard (Oversikt)draft-1-portfolio.html - Portfolio pagedraft-1-sparing.html - Savings pagedraft-1-gjeld.html - Debt pagedraft-1-pensjon.html - Pension pagedraft-1-kalkulatorer.html - Calculators page
MANDATORY Verification Workflow for Frontend Tasks:
pnpm --filter frontend dev &
node scripts/playwright-verify.js http://localhost:5173/[page] [task-name]
What to verify (script checks automatically):
- Page loads successfully (no crash)
- No JavaScript console errors
- Screenshot captured for visual review
Manual verification (review script output):
- Layout matches design draft structure
- Components are positioned correctly
- Norwegian text is displayed properly
- Number formatting (space as thousands separator, e.g., "123 456,78 kr")
- Color scheme matches Nordic Minimal palette
- Typography (Cormorant Garamond for headings, DM Sans for body)
Example verification session:
node scripts/playwright-verify.js http://localhost:5173/portfolio portfolio-page
node scripts/playwright-verify.js http://localhost:5173/portfolio --interactive
If verification fails:
- Fix the issues before marking complete
- Re-run verification after fixes
- Document what was fixed in Progress Log
Build verification:
pnpm --filter frontend build
pnpm --filter backend build
pnpm lint
pnpm --filter frontend type-check
pnpm --filter backend type-check
Step 10: Complete and Move to Done
🚨 CRITICAL: Update Acceptance Criteria Checkboxes
Before marking complete, you MUST check off all acceptance criteria in the task file:
- Change
- [ ] to - [x] for each completed item
- If an item cannot be completed, document why in the Resolution section
- A task with unchecked acceptance criteria is NOT DONE
Before marking complete, verify the Verification Checklist (in task file):
## Verification
- [x] All acceptance criteria met AND CHECKED OFF IN TASK FILE
- [x] Frontend builds successfully (`pnpm --filter frontend build`)
- [x] Backend builds successfully (`pnpm --filter backend build`)
- [x] TypeScript compilation clean (no errors)
- [x] ESLint passes
- [x] Manual testing complete
- [x] Norwegian formatting verified
- [x] Error handling tested
- [x] Code reviewed (self-review)
- [x] **🚨 Playwright CLI verification** (MANDATORY for frontend tasks)
🚨 Playwright CLI verification is MANDATORY for ALL frontend tasks:
The task is NOT complete until you have:
- Run
node scripts/playwright-verify.js <url> <task-name>
- Verified no console errors in output
- Reviewed screenshot in
.playwright-output/
- Confirmed layout and functionality match requirements
DO NOT skip this step. Frontend tasks without Playwright verification are INCOMPLETE.
Then finalize:
-
Update Resolution section with final outcome:
## Resolution
Successfully implemented backend Express server with complete middleware stack.
**Implementation Summary**:
- Created Express app with TypeScript in `/backend/src/index.ts`
- Configured Winston logger for structured logging
- Implemented global error handler in `/backend/src/middleware/errorHandler.ts`
- Added rate limiting middleware (100 req/min general, 10 req/min calculators)
- Set up CORS for frontend access
- Created health check endpoint at `/api/v1/health`
- Configured graceful shutdown handlers
**Files created**:
- `/backend/src/index.ts` - Main server entry point
- `/backend/src/config/environment.ts` - Environment validation
- `/backend/src/utils/logger.ts` - Winston logger
- `/backend/src/middleware/errorHandler.ts` - Global error handler
- `/backend/src/middleware/rateLimiter.ts` - Rate limiting
- `/backend/src/routes/index.ts` - Route aggregator
**Test results**:
- ✅ Server starts on port 3000
- ✅ Health endpoint responds: `GET http://localhost:3000/api/v1/health`
- ✅ CORS allows frontend origin
- ✅ Rate limiting works (tested with multiple requests)
- ✅ Error responses follow standard format
- ✅ TypeScript build succeeds
- ✅ All 12 acceptance criteria met
**Next steps**:
- Ready for `002-FEATURE-cosmosdb-connection.md`
-
Move file to done:
Move: .task-board/in-progress/001-FEATURE-backend-express-server.md
To: .task-board/done/001-FEATURE-backend-express-server.md
-
Update PLANNING-BOARD.md:
- Remove completed item from "Top Priorities"
- Add to "Recently Completed" section
- Add next priority from backlog (if applicable)
- Keep board at 3-5 items maximum
## Recently Completed
- ✅ **001-FEATURE-backend-express-server** (Completed: 2025-11-28) - Foundation for API development
-
Update README statistics (.task-board/README.md):
Total Plans: 20
├── Backlog: 18
├── In Progress: 0
├── Done: 2
└── On Hold: 0
Subagent Execution Strategy
CRITICAL: Use Subagents for Each Task
IMPORTANT: Each task from the backlog MUST be executed using the Task tool with an appropriate subagent. This ensures:
- Focused context for each task
- Proper model selection based on complexity
- Clear separation between tasks
- Better resource utilization
Model Selection by Complexity
DEFAULT MODEL: haiku - Use haiku for most tasks unless complexity requires sonnet.
| Complexity | Model | Examples |
|---|
| Standard (default) | haiku | CSS fixes, text changes, simple components, form fields, API endpoints with clear patterns, bug fixes, refactoring |
| Complex | sonnet | D3.js visualizations, complex business logic, multi-file architectural changes, intricate state management, complex validation logic |
Use haiku when:
- Task follows existing patterns in the codebase
- Requirements are clear and well-defined
- Single feature or component implementation
- Straightforward API endpoint
- CSS/styling work
- Simple to medium React components
Use sonnet when:
- Task involves D3.js or complex visualizations
- Complex state management across multiple stores
- Architectural decisions needed
- Multi-step business logic with edge cases
- Integration of multiple systems (e.g., CosmosDB + LLM + frontend)
Sequential Task Execution - TASKS ARE DONE IN ORDER
CRITICAL: Execute tasks ONE AT A TIME, IN ORDER. This is non-negotiable.
❌ WRONG: Start multiple tasks in parallel
❌ WRONG: Skip ahead to "more interesting" tasks
❌ WRONG: Pick tasks out of order
✅ RIGHT: Complete task 071 → Move to done → Start task 072 → Complete → Start 073...
The workflow is strictly sequential:
- Pick the FIRST numbered task from PLANNING-BOARD
- Execute it with a subagent (haiku by default)
- Verify completion (including Playwright CLI for frontend)
- Move to done
- Pick the NEXT numbered task
- Repeat
Why sequential and in-order:
- Tasks are numbered to respect dependencies
- Foundation work must come before features
- Prevents broken builds and incomplete features
- Makes progress predictable and trackable
Task Ordering is MANDATORY
Tasks in the backlog are numbered for a reason. The numbering reflects:
- Dependency order (lower numbers are prerequisites)
- Logical implementation sequence
- Foundation → Features → Polish
NEVER skip tasks unless:
- User explicitly requests a different order
- A task is blocked by external factors (and you've asked user)
Example dependency chain:
071-redirect → 072-login-redirect → 073-user-model → 074-account-model → ...
How to Invoke Subagents
Use the Task tool to spawn a subagent for each task:
Task tool parameters:
- subagent_type: "general-purpose"
- model: "haiku" (default) or "sonnet" (for complex tasks)
- prompt: Detailed task instructions
- description: Short 3-5 word summary
Example subagent invocation for a standard task:
Task tool:
subagent_type: "general-purpose"
model: "haiku"
description: "Implement user routes"
prompt: |
Implement the user API routes as specified in:
.task-board/in-progress/081-FEATURE-user-routes.md
This task is tracked in the task board system.
🚨 READ CLAUDE.md FIRST - it contains all project patterns, conventions, and tech stack.
Follow all patterns from CLAUDE.md.
Update the task file in .task-board/in-progress/ with progress.
Mark acceptance criteria as complete in the task file.
🚨 CRITICAL RESTRICTIONS:
1. Work ONLY on this task from .task-board/ - no ad-hoc work
2. NEVER use git commands (git add, commit, push, status, diff, etc.)
3. Use Read tool (NOT cat/head/tail)
4. Use Write tool (NOT echo/cat heredoc)
5. Use Edit tool (NOT sed/awk)
6. Use Glob tool (NOT find/ls for search)
7. Use Grep tool (NOT grep/rg bash commands)
8. 🚨 CHECK OFF acceptance criteria as you complete them (change [ ] to [x])
NEVER use bash for file operations when a built-in tool exists.
NEVER run ANY git commands - user handles version control manually.
🚨 ACCEPTANCE CRITERIA: As you complete each acceptance criterion,
UPDATE THE TASK FILE to check it off: change "- [ ]" to "- [x]".
A task with unchecked acceptance criteria is NOT DONE.
When done, provide a summary of:
- Files created/modified
- All acceptance criteria status (MUST be checked off in task file)
- Any issues encountered
Example for a complex frontend task (needs sonnet):
Task tool:
subagent_type: "general-purpose"
model: "sonnet"
description: "Build D3.js area chart"
prompt: |
Implement the AreaChart component with D3.js as specified in:
.task-board/in-progress/048-FEATURE-area-chart-component.md
This task is tracked in the task board system.
🚨 READ CLAUDE.md FIRST - it contains all project patterns, conventions, and tech stack.
This involves complex D3.js visualization work.
Update the task file in .task-board/in-progress/ with progress.
🚨 CRITICAL RESTRICTIONS:
1. Work ONLY on this task from .task-board/ - no ad-hoc work
2. NEVER use git commands (git add, commit, push, status, diff, etc.)
3. Use Read tool (NOT cat/head/tail)
4. Use Write tool (NOT echo/cat heredoc)
5. Use Edit tool (NOT sed/awk)
6. Use Glob tool (NOT find/ls for search)
7. Use Grep tool (NOT grep/rg bash commands)
8. 🚨 CHECK OFF acceptance criteria as you complete them (change [ ] to [x])
NEVER use bash for file operations when a built-in tool exists.
NEVER run ANY git commands - user handles version control manually.
🚨 ACCEPTANCE CRITERIA: As you complete each acceptance criterion,
UPDATE THE TASK FILE to check it off: change "- [ ]" to "- [x]".
A task with unchecked acceptance criteria is NOT DONE.
After implementation, VERIFY using Playwright CLI:
node scripts/playwright-verify.js http://localhost:5173/[page] area-chart
Provide summary with verification results and update task file.
Working Through the Backlog - AUTONOMOUS MODE
🚨 CRITICAL: This skill runs ALL tasks automatically until backlog is empty.
This skill processes the entire backlog autonomously, IN ORDER, without stopping:
LOOP until backlog is empty:
1. Read PLANNING-BOARD to get the FIRST numbered task
2. Move task to in-progress/
3. Spawn subagent with Task tool (haiku by default)
4. Subagent implements and verifies (Playwright CLI for frontend)
5. Move task to done/
6. Update PLANNING-BOARD.md
7. AUTOMATICALLY continue to next task (NO user prompt needed)
DO NOT STOP between tasks. Continue until:
- All tasks in PLANNING-BOARD are complete, OR
- A critical blocker prevents progress, OR
- User explicitly interrupts
After completing a task, IMMEDIATELY start the next one. No waiting for user confirmation.
Constraints and Guidelines
Critical Constraints
- 🚨 ALL WORK THROUGH TASK BOARD: Every task must come from
.task-board/. Never do ad-hoc work outside the system.
- 🚨 NEVER use git commands: No git add, commit, push, status, diff, or ANY git command. User handles all version control.
- Follow finans architecture patterns: See CLAUDE.md for complete patterns
- Norwegian localization: All UI text in Norwegian, use format utilities
- Keep PLANNING-BOARD.md lean: Maximum 3-5 items, concise status notes
- Real-time updates: Update task files in
.task-board/in-progress/ frequently
- Sequential execution: Execute tasks fully before starting the next (but continue automatically)
- No breaking changes: Maintain backward compatibility
- Security first: Never commit secrets, always validate input
- Respect task ordering: Tasks are numbered for dependency reasons
Development Environment
Package manager: Always use pnpm (not npm or yarn)
Common commands:
pnpm install
pnpm dev
pnpm --filter frontend dev
pnpm --filter backend dev
pnpm build
pnpm lint
pnpm --filter frontend type-check
pnpm --filter backend type-check
Environment files:
- ✅ Already configured:
backend/.env and frontend/.env
- ✅ Gitignored (never commit)
- OAuth credentials already set up
CosmosDB Emulator:
.\emulator.bat
https://localhost:8081/_explorer/
Code Quality Standards
TypeScript:
- Strict mode enabled
- No
any types without justification
- Explicit return types for complex functions
- Interface for object shapes
React/Frontend:
- Functional components only
- Custom hooks for reusable logic
- Destructure props in function signature
- Use Nordic Minimal CSS classes for styling
Express/Backend:
- Async/await (no callbacks)
- Proper error handling (try/catch)
- Parameterized queries (prevent injection)
- Structured logging with Winston
Imports:
- External packages (alphabetical)
- Internal packages/aliases (alphabetical)
- Relative imports (alphabetical)
Documentation Requirements
Update docs DURING and AFTER work:
- DURING: Track implementation progress in task file Progress Log
- AFTER: Update Resolution section with final outcome
Key docs to maintain:
- Task files (Progress Log, Resolution, Verification)
PLANNING-BOARD.md (current priorities and status)README.md (statistics)
Success Criteria
A work session is complete when:
For Each Task (executed via subagent):
For the Overall Session (AUTONOMOUS):
Key Reminders:
- 🚨 AUTONOMOUS MODE - run ALL tasks without stopping, no user prompts between tasks
- 🚨 USE TASK BOARD - all work tracked in
.task-board/, never work outside the system
- 🚨 NO GIT COMMANDS - never run any git command, user handles version control
- Use haiku by default - only use sonnet for truly complex tasks
- Tasks done IN ORDER - respect numbering from PLANNING-BOARD.md
- Playwright CLI for frontend - no exceptions
- Built-in tools over bash - Read/Write/Edit/Glob/Grep, never cat/grep/find/sed
Handling Edge Cases
If PLANNING-BOARD is Empty
Ask the user:
The PLANNING-BOARD is currently empty. Would you like me to:
1. Add the top 3-5 numbered tasks from backlog/ (001-005)?
2. Review the entire backlog and make custom recommendations?
3. Wait for you to manually select priorities?
If Top Priority is Blocked
Identify the blocker and ask:
The top priority (009-FEATURE-portfolio-dashboard) is blocked by:
- Requires 008-FEATURE-portfolio-api-endpoints (not complete)
- Requires 004-FEATURE-norwegian-localization (not complete)
Would you like me to:
1. Work on the blockers first (008, then 004)?
2. Skip to the next unblocked item?
3. Re-prioritize the board?
If Task is Unclear
ALWAYS ask clarifying questions before proceeding. Examples:
- "The task mentions 'optional D3.js chart' - should I implement this for MVP or skip it?"
- "Should user profile editing work immediately or require email verification?"
- "For error messages, should they be Norwegian or English (for developers)?"
- "Should the dashboard auto-refresh data or require manual refresh?"
If Task is Too Large
Break it down:
This task (009-FEATURE-portfolio-dashboard) seems too complex for a single implementation.
I recommend breaking it into:
1. 009a-FEATURE-dashboard-data-fetching.md (API integration - 1 day)
2. 009b-FEATURE-net-worth-chart.md (D3.js chart - 2 days)
3. 009c-FEATURE-account-table.md (Table component - 1 day)
Should I create these sub-tasks and start with 009a?
If In-Progress Folder Has Multiple Tasks
Ask before starting new work:
The in-progress/ folder already has 2 tasks:
- 001-FEATURE-backend-express-server (50% complete)
- 003-FEATURE-frontend-react-initialization (25% complete)
Would you like me to:
1. Continue one of these existing tasks?
2. Move one to on-hold/ and start the new priority?
3. Finish one before starting new work?
(Recommendation: Limit work-in-progress to 1-2 tasks for focus)
Integration with Other Skills
Task-Discovery Skill
If the backlog is empty or stale:
- Use the task-discovery skill to analyze gaps and generate new tasks
- New tasks get numbered and added to
backlog/
- Update
PLANNING-BOARD.md with top priorities
- Then use this start-working skill to implement
Task-Board Skill (Planning)
If the user describes a new feature during work:
- Use the task-board skill to create a comprehensive plan
- The new task gets added to
backlog/ with next available number
- Add to
PLANNING-BOARD.md if high priority
- Continue with current work or switch to new priority
This skill is optimized for implementation work (90% of development time).
Repository-Specific Context
Project Structure
finans/
├── backend/ # Express API server
│ ├── src/
│ │ ├── config/ # Environment, CosmosDB setup
│ │ ├── routes/ # Express routes
│ │ ├── controllers/ # Request handlers
│ │ ├── services/ # Business logic, DB access
│ │ ├── validators/ # Input/business validation
│ │ ├── middleware/ # Auth, error handling, logging
│ │ └── utils/ # Helper functions
│ ├── .env # Environment variables (gitignored)
│ └── package.json
├── frontend/ # React + Vite app
│ ├── src/
│ │ ├── features/ # Feature-based organization
│ │ │ ├── auth/ # Login, user management
│ │ │ ├── portfolio/ # Portfolio tracking
│ │ │ ├── calculators/ # Financial calculators
│ │ │ └── dashboard/ # Dashboard and charts
│ │ ├── shared/ # Shared code
│ │ │ ├── components/ # Reusable UI components
│ │ │ ├── hooks/ # Custom hooks
│ │ │ ├── utils/ # Utilities (Norwegian formatting)
│ │ │ └── api/ # Axios client, TanStack Query
│ ├── .env # Environment variables (gitignored)
│ └── package.json
├── components/ # Shared component library
│ ├── src/ # Components + Storybook
│ └── package.json
├── e2e/ # Playwright E2E tests (future)
├── .task-board/ # Task management system
│ ├── PLANNING-BOARD.md # Current priorities (max 3-5)
│ ├── README.md # System documentation
│ ├── WORKFLOW.md # Complete workflow guide
│ ├── backlog/ # Planned tasks
│ ├── in-progress/ # Active work (limit 1-2)
│ ├── done/ # Completed tasks
│ └── on-hold/ # Deferred tasks
├── .claude/ # Claude Code configuration
│ ├── CLAUDE.md # Project instructions
│ └── skills/ # Custom skills
├── emulator.bat # Start CosmosDB Emulator
└── package.json # Root monorepo config
Technology Stack
Backend:
- Node.js 18+ with Express
- TypeScript (strict mode)
- Azure CosmosDB (NoSQL)
- Winston (logging)
- Helmet (security)
- CORS, rate limiting
Frontend:
- React 18 with TypeScript
- Vite (build tool)
- BeerCSS + Material UI (styling)
- D3.js (visualizations)
- TanStack Query (server state)
- Zustand (client state)
- React Hook Form + Zod (forms)
- Axios (HTTP client)
Tooling:
- pnpm (package manager)
- ESLint + Prettier
- Playwright (E2E tests - future)
Key Conventions
Norwegian Context:
- UI language: Norwegian (Bokmål)
- Numbers:
123 456,78 kr
- Dates:
dd.MM.yyyy
- Currency: NOK (kroner)
File Naming:
- Components:
PascalCase.tsx
- Utilities:
camelCase.ts
- Types:
camelCase.types.ts
API Endpoints:
- Base:
/api/v1
- REST conventions (GET, POST, PATCH, DELETE)
- Standard response format
Git Workflow (USER MANAGED - agent never runs git):
- Main branch:
main
- Conventional Commits format
- Never commit
.env files
- 🚨 Agent NEVER runs git commands - user handles all version control
See Also
