---
title: "Development Workflow"
description: "Plan-Document-Execute-Verify development cycle and team standards for Sage.is AI-UI."
date: 2025-11-28
tags:
  - workflow
  - development
  - process
  - meta
---

# Sage.is AI-UI Development Workflow

**Before Starting Any Work ALWAYS add to TODO.md first:**

```markdown
## 🔥 This Week (Current Date)
### 🔥 [Task Category]: [Task Name]
- [ ] **[Task Name]**: Brief description
  - [ ] Subtask 1
  - [ ] Subtask 2
  - [ ] Test/verify step
  - [ ] Documentation update
```

**NEVER start work without:**
- Adding the task to TODO.md at the top (current week section)
- Getting approval for significant changes
- Understanding the complete scope

**TODO Organization Rules:**
- **Current work goes at the top** - Always add new tasks to the current week section
- **Use priority emojis** - 🔥 Critical, 🔶 High, 🔷 Medium, 🔹 Low, ✅ Done
- **Move completed work down** - When tasks are done, move them to "Previous Weeks" section
- **Keep reverse chronological order** - Newest completed work appears first in Previous WeeksCore Principles

Every development task follows the **Plan-Document-Execute-Verify** cycle:


0. **DRY** **KISS** - Don't Repeat Yourself (ever in Code) and Keep It Simple, Stupid
1. **Plan** - Add to TODO before doing any work
2. **Document** - Update docs and README as needed
3. **Execute** - Implement changes following standards
4. **Verify** - Test, commit, and check off completed items

Our Zeroth rule is to keep things **DRY** and **KISS**. This means we avoid code duplication and keep our solutions as simple as possible.

## Standard Operating Procedure

### Before Starting Any Work

**ALWAYS add to TODO.md first:**

```markdown
## [Category] TODOs
- [ ] **[Task Name]**: Brief description
  - [ ] Subtask 1
  - [ ] Subtask 2
  - [ ] Test/verify step
  - [ ] Documentation update
```

**NEVER start work without:**
- Adding the task to TODO.md
- Getting approval for significant changes
- Understanding the complete scope

### Planning Requirements

For each task, define:
- **Scope** - What exactly needs to be done
- **Dependencies** - What must be completed first
- **Testing** - How to verify it works
- **Documentation** - What docs need updates

### Documentation Standards

**Always update documentation when:**
- Adding new features or processes
- Changing existing functionality
- Creating new files or directories
- Modifying configuration

**Documentation locations:**
- `README.md` - Quick start and overview
- `docs/` - Detailed guides
- `TODO.md` - Current and completed work
- Inline code comments - Complex logic

### Execution Standards

**File Management:**
- Use skip-worktree for config files that need local customization
- Follow naming conventions (kebab-case for files)
- Organize code logically in appropriate directories

**Git Workflow:**
- Descriptive commit messages
- Atomic commits (one logical change per commit)
- Check off TODO items in commit messages when completed

**Code Quality:**
- Follow project conventions
- Test changes before committing
- Use tools appropriately (Makefile targets, npm scripts)

### Verification Process

**Before marking TODO items complete:**
- [ ] Feature/fix works as expected
- [ ] No new errors introduced
- [ ] Documentation updated
- [ ] README links current
- [ ] Committed to version control

**After completion:**
- Mark TODO items with ✅
- Update progress in commit messages
- Note any follow-up tasks needed

## Communication Protocol

### Seeking Approval

**Always check before starting:**
- Significant feature additions
- Process changes
- Large refactoring
- External integrations

**Use clear language:**
- "Ready to proceed with [task] when approved"
- "This will affect [areas] - proceed?"
- "Plan complete, awaiting go-ahead"

### Progress Updates

**Format: [Status] [Task] - [Details]**
- ✅ **Completed** - [Task] with summary
- 🔄 **In Progress** - [Task] current step
- 📋 **Planned** - [Task] ready to start
- ⚠️ **Blocked** - [Task] waiting on [dependency]

## Project-Specific Standards

### Documentation Management

**README.md sections:**
- Quick Start
- Initial Setup
- Documentation (links to all docs/)
- Environment System
- Troubleshooting
- Technical Details

**Required documentation:**
- All files in `docs/` must be linked in README
- New processes get dedicated documentation
- Configuration changes need setup instructions

### TODO Management

`TODO.md` is the canonical task list. `KANBAN.canvas` auto-generates from it and inline source tags.

**Kanban columns** (see the convention table at the top of `TODO.md`):

| Column      | Markdown section  | Inline tag  |
|-------------|-------------------|-------------|
| Backlog     | `## Backlog`      | `# NOTE:`   |
| TODO        | `## TODO`         | `# TODO:`   |
| In Progress | `## In Progress`  | `# FIXME:`  |
| Bugs        | `## Bugs`         | `# BUG:`    |
| Done        | `- [x]` items / `## Done` | —   |

**Workflow:**
1. New work starts as `- [ ]` in TODO, grouped by version milestone.
2. When you begin work, move the item to In Progress and tag the relevant source line with `# FIXME:`.
3. When done, check off the item (`- [x]`) and remove the inline tag.
4. Periodically move checked items to `docs/completed-todos.md`.

**Inline tags in source:**
- `# TODO:` — tracked work not yet started.
- `# FIXME:` — actively being worked on.
- `# BUG:` — confirmed defect.
- `# NOTE:` — documentation, not a work item (unless it flags deferred cleanup).
- `# DEPRECATED:` — scheduled for removal; track in TODO.md with the target version.

### Admin Integration Standards

**For data that should be CMS-managed:**
1. Add TODO for admin collection setup
2. Design collection structure matching existing data
3. Plan template integration
4. Test admin interface
5. Document staff process
6. Migrate from static to admin-managed

### Configuration Management

**Files requiring skip-worktree:**
- `src/admin/config.yml` - CMS configuration
- Any file needing local customization

**Setup process:**
- Add to `make setup` target
- Document in README and dedicated guide
- Include in onboarding documentation

## Styling with Startr.Style

This project uses [Startr.Style](https://startr.style) as its primary CSS framework. Startr.Style is a utility-complete CSS framework (under 50KB / 8KB gzipped) that uses inline CSS custom properties instead of class-based utilities.

### Why Startr.Style

- **Zero compilation** — no build step, no purging, no config files
- **Full CSS spec access** — developer-defined values, not restricted presets
- **Fraction of the size** — utilities defined by property only, values are yours
- **Automatic base styling** — semantic HTML looks good out of the box
- **Responsive, dark mode, hover** — built-in with suffixes

### How It Works

Style elements using `--property:value` in the `style` attribute:

```html
<!-- Layout -->
<div style="--d:flex; --ai:center; --jc:space-between; --g:1rem">

<!-- Spacing & borders -->
<div style="--p:0.6rem; --br:0.5rem; --b:1px solid var(--color-gray-200)">

<!-- Typography -->
<span style="--size:0.8rem; --weight:500; --c:var(--color-gray-600)">
```

### Common Shorthands

| Shorthand | CSS Property | Example |
|-----------|-------------|---------|
| `--d` | display | `--d:flex` |
| `--p` | padding | `--p:1rem` |
| `--m` | margin | `--m:0.5rem` |
| `--bg` / `--bgc` | background / background-color | `--bg:var(--color-sky-500)` |
| `--c` | color | `--c:white` |
| `--br` | border-radius | `--br:0.5rem` |
| `--b` | border | `--b:1px solid var(--color-gray-300)` |
| `--w` / `--h` | width / height | `--w:100%` |
| `--ai` | align-items | `--ai:center` |
| `--jc` | justify-content | `--jc:space-between` |
| `--fd` | flex-direction | `--fd:column` |
| `--g` | gap | `--g:0.5rem` |
| `--ta` | text-align | `--ta:center` |
| `--size` | font-size | `--size:0.8rem` |
| `--weight` | font-weight | `--weight:600` |
| `--pos` | position | `--pos:relative` |

### Responsive Suffixes

Append a breakpoint suffix to any property:

| Suffix | Min Width |
|--------|-----------|
| `-sm` | 640px |
| `-md` | 768px |
| `-lg` | 1024px |
| `-xl` | 1280px |
| `-pt` | print only |

```html
<!-- Hidden on mobile, flex on medium+ -->
<div style="--d:none; --d-md:flex">
```

### Dark Mode & Interactive States

- **Dark mode:** prefix with `--dark-` (e.g., `--dark-bg:var(--color-gray-800)`)
- **Hover:** prefix with `--hvr-` (e.g., `--hvr-bg:var(--color-sky-600)`)

```html
<button style="--bgc:var(--color-gray-100); --dark-bgc:var(--color-gray-800); --hvr-bgc:var(--color-gray-200)">
  Theme-aware button
</button>
```

### Rules

- **Always use Startr.Style** for component styling — do not replace with Tailwind utility classes or standalone CSS classes
- **Use project color variables** (`var(--color-gray-200)`, `var(--color-sky-500)`, etc.) defined in `app/static/assets/custom.css`
- **Keep it inline** — Startr.Style is designed for inline `style` attributes, not separate stylesheets
- Refer to [startr.style](https://startr.style) for the full property reference

## Quality Assurance

### Pre-Commit Checklist

- [ ] TODO updated with progress
- [ ] Documentation reflects changes
- [ ] README links are current
- [ ] No broken links or references
- [ ] Code follows project conventions
- [ ] Changes tested locally

### Review Standards

**Code review focuses on:**
- Adherence to workflow process
- Documentation completeness
- TODO accuracy and progress
- Standard compliance

### Continuous Improvement

**Regular workflow reviews:**
- Monthly TODO cleanup
- Quarterly process refinement
- Document lessons learned
- Update standards as needed

## Tools and Automation

### Makefile Targets

Standard targets for common tasks:
- `make setup` - Configure local environment
- `make help` - Show available commands
- Project-specific build/deploy targets

### Git Integration

**Commit message format:**
```
[Type]: [Summary]

- [Change 1]
- [Change 2]
- Mark TODO item as complete/in progress
```

**Types:** Add, Update, Fix, Remove, Refactor, Document

### Documentation Tools

- Markdown for all documentation
- Consistent heading structure
- Clear, concise language following Sage.is AI-UI Writing Guidelines
- Regular link validation

### Testing Standards

**Test Framework:**
- pytest with pytest-django for Django integration
- pytest-cov for coverage reporting
- All tests in `tests.py` files within app directories

**Test Configuration:**
- `pytest.ini` - Main pytest configuration
- `conftest.py` - Shared fixtures and Django setup
- Tests run with `--nomigrations` and `--reuse-db` for speed

**Testing Commands:**
```bash
make test                 # Run all tests
make test_verbose         # Run with verbose output
make test_coverage        # Run with coverage report
make test_experiences     # Run only experiences app tests
make test_quick          # Run excluding slow tests
```

**Test Categories (using markers):**
- `@pytest.mark.unit` - Unit tests (isolated, fast)
- `@pytest.mark.integration` - Integration tests
- `@pytest.mark.slow` - Slow tests (can be excluded)
- `@pytest.mark.django_db` - Tests requiring database

**Writing Tests:**
- One test file per app (`app/tests.py`)
- Test classes for each model/view
- Descriptive test names explaining what is tested
- Use fixtures from `conftest.py` for common setup
- Mock external dependencies

**Test Coverage:**
- Aim for 80%+ coverage on critical paths
- 100% coverage on new models and core business logic
- Coverage reports generated in `htmlcov/` directory

## Success Metrics

**Process adherence:**
- All work starts with TODO entry
- Documentation stays current
- No surprise changes without planning
- Clear approval process followed

**Quality indicators:**
- Accurate TODO progress tracking
- Complete documentation coverage
- Working links and references
- Consistent code standards

**Team efficiency:**
- Reduced context switching
- Clear handoff documentation
- Predictable development cycle
- Minimal rework needed

## Getting Started

**For new team members:**
1. Read this workflow document
2. Run `make setup`
3. Review current TODO.md
4. Practice the plan-document-execute-verify cycle on small tasks
5. Ask questions before starting significant work

**For existing team members:**
1. Adopt this process for all new work
2. Migrate existing workflows gradually
3. Update TODO.md with current status
4. Help refine and improve the process

---

*This workflow document is living documentation. Update it as the process evolves and improve it based on team feedback and project needs.*
