Building a Feature with sudocode

Tutorial Overview

This tutorial walks through building a complete user authentication system using sudocode’s spec-driven development workflow. You’ll learn how to create specifications, plan implementation with AI agents, manage dependencies, provide feedback, and iterate to completion.

Create high-level specification

Define what you want to build

Break down into sub-specs

Organize complex features hierarchically

Plan implementation with agent

AI agent creates issues from specs

Execute issues in dependency order

Agents claim and complete work

Handle blockers

Model dependencies and work on blockers

Provide feedback

Surface ambiguities and refine specs

Iterate to completion

Track progress and close work

Step 1: Initialize Project

First, set up a sudocode project in your repository:

# Navigate to your project
cd my-app

# Initialize sudocode
sudocode init

Expected output

✓ Initialized sudocode project
  Directory: .sudocode/
  Database: .sudocode/sudocode.db

Next steps:
  - Create your first spec: sudocode spec create "Feature Name"
  - Add .sudocode/sudocode.db to .gitignore

Verify structure:

ls -la .sudocode/

Output:

.sudocode/
├── specs/
│   └── specs.jsonl
├── issues/
│   └── issues.jsonl
└── sudocode.db

Add to .gitignore:

echo ".sudocode/sudocode.db*" >> .gitignore
git add .gitignore .sudocode/
git commit -m "Initialize sudocode"

Step 2: Create High-Level Specification

Define what you want to build at a high level:

sudocode spec create "User Authentication System" \
  --priority 0 \
  --tags auth,security,oauth

Expected output

Created SPEC-001

Spec created at:
  .sudocode/specs/user-authentication-system.md

Edit the spec to add requirements and design details.

Edit the spec file:

vim .sudocode/specs/user-authentication-system.md

Add content:

---
id: SPEC-001
title: User Authentication System
priority: 0
status: draft
tags:
  - auth
  - security
  - oauth
created_at: '2025-10-29T10:00:00Z'
updated_at: '2025-10-29T10:00:00Z'
---

# User Authentication System

## Overview

Implement a secure user authentication system supporting OAuth 2.0
authentication with Google and GitHub providers. The system should
handle user sessions, token management, and security best practices.

## Requirements

### Functional Requirements
- [ ] Support Google OAuth 2.0 authentication
- [ ] Support GitHub OAuth 2.0 authentication
- [ ] Secure token storage
- [ ] Automatic token refresh
- [ ] User profile synchronization
- [ ] Session management
- [ ] Logout functionality

### Non-Functional Requirements
- [ ] PKCE for all OAuth flows (security)
- [ ] Token expiration handling
- [ ] Rate limiting on auth endpoints
- [ ] Audit logging for authentication events
- [ ] Response time < 500ms for auth checks

## Architecture

### Components
- **OAuth Middleware** - Express middleware for OAuth flows
- **Token Manager** - Handles token storage and refresh
- **Session Store** - Redis-backed session management
- **User Profile Service** - Syncs user data from providers

### Data Flow
1. User clicks "Sign in with Google/GitHub"
2. Redirect to OAuth provider
3. User authorizes application
4. Callback receives authorization code
5. Exchange code for access/refresh tokens
6. Store tokens securely (encrypted)
7. Create user session
8. Redirect to dashboard

## Security Considerations
- Use PKCE to prevent authorization code interception
- Store tokens in httpOnly cookies (not localStorage)
- Encrypt tokens at rest
- Implement CSRF protection via state parameter
- Rate limit authentication endpoints
- Log all authentication events

## Open Questions
- Should we support email/password fallback authentication?
- Token expiration times: use defaults or custom?
- How to handle token revocation?
- Session timeout duration?

## Success Criteria
- [ ] Users can authenticate with Google
- [ ] Users can authenticate with GitHub
- [ ] Tokens refresh automatically before expiration
- [ ] No OWASP Top 10 vulnerabilities
- [ ] Auth flow completes in < 3 seconds
- [ ] 100% test coverage on auth flows

Sync and commit:

sudocode sync --from-markdown
git add .sudocode/
git commit -m "Add authentication system spec (SPEC-001)"

Step 3: Break Down into Sub-Specs

For complex features, create sub-specifications:

# OAuth 2.0 implementation details
sudocode spec create "OAuth 2.0 Integration" \
  --parent SPEC-001 \
  --priority 1 \
  --tags auth,oauth

# Session management details
sudocode spec create "Session Management" \
  --parent SPEC-001 \
  --priority 1 \
  --tags auth,session

# Security hardening details
sudocode spec create "Security Hardening" \
  --parent SPEC-001 \
  --priority 2 \
  --tags auth,security

Expected output

Created SPEC-002
Spec created at: .sudocode/specs/oauth-2-0-integration.md

Created SPEC-003
Spec created at: .sudocode/specs/session-management.md

Created SPEC-004
Spec created at: .sudocode/specs/security-hardening.md

View hierarchy:

sudocode spec list

Output:

Specs (4 total)

ID        Title                          Priority  Status
────────────────────────────────────────────────────────────
SPEC-001  User Authentication System     P0        draft
  SPEC-002  OAuth 2.0 Integration        P1        draft
  SPEC-003  Session Management           P1        draft
  SPEC-004  Security Hardening           P2        draft

Edit SPEC-002 with OAuth details:

---
id: SPEC-002
title: OAuth 2.0 Integration
parent_id: SPEC-001
priority: 1
status: draft
tags:
  - auth
  - oauth
---

# OAuth 2.0 Integration

Parent: [[SPEC-001]]

## OAuth Providers

### Google OAuth 2.0
- Client ID and secret from Google Cloud Console
- Scopes: `openid profile email`
- Redirect URI: `https://app.example.com/auth/google/callback`

### GitHub OAuth 2.0
- Client ID and secret from GitHub Developer Settings
- Scopes: `read:user user:email`
- Redirect URI: `https://app.example.com/auth/github/callback`

## Implementation Details

### Authorization Flow
1. Generate PKCE code verifier (43-128 chars)
2. Compute code challenge: `SHA256(verifier)`
3. Redirect to provider with challenge
4. User authorizes
5. Provider redirects with auth code
6. Exchange code + verifier for tokens

### Token Structure
```json
{
  "access_token": "ya29.a0...",
  "refresh_token": "1//0g...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

Token Storage

Encrypt tokens using AES-256-GCM
Store in database with user association
Never expose tokens to client
Use httpOnly cookies for session

Configuration

interface OAuthConfig {
  google: {
    clientId: string;
    clientSecret: string;
    redirectUri: string;
  };
  github: {
    clientId: string;
    clientSecret: string;
    redirectUri: string;
  };
}

Error Handling

Invalid authorization code → redirect to error page
Token exchange fails → log error, retry once
Token expired → use refresh token automatically
Refresh token invalid → force re-authentication

**Commit all specs:**

```bash
sudocode sync --from-markdown
git add .sudocode/
git commit -m "Add OAuth and session sub-specs (SPEC-002, SPEC-003, SPEC-004)"

Step 4: Plan Implementation with AI Agent

Now, ask an AI agent (via MCP) to create an implementation plan from the specs. Agent conversation:

You: "I have SPEC-001 for a user authentication system with 3 sub-specs.
     Can you create a complete implementation plan with proper dependencies?"

Agent: "I'll analyze the specs and create a detailed implementation plan."

Agent’s process (via MCP):

// 1. Agent reads specs
const spec1 = await show_spec("SPEC-001");
const spec2 = await show_spec("SPEC-002");
const spec3 = await show_spec("SPEC-003");
const spec4 = await show_spec("SPEC-004");

// 2. Agent creates foundation issues
const issue1 = await upsert_issue({
  title: "Set up OAuth provider configuration",
  description: `Configure OAuth 2.0 providers (Google and GitHub).

## Tasks
- [ ] Register OAuth apps with Google Cloud Console
- [ ] Register OAuth app with GitHub
- [ ] Configure client IDs and secrets in environment
- [ ] Set up redirect URIs
- [ ] Document environment variables

Implements [[SPEC-002]]`,
  priority: 0,
  tags: ["auth", "oauth", "setup", "p0"]
});
await link("ISSUE-001", "SPEC-002", "implements");

// 3. Agent creates dependent issues
const issue2 = await upsert_issue({
  title: "Implement OAuth token exchange",
  description: `Exchange authorization codes for access/refresh tokens.

## Tasks
- [ ] Implement PKCE code generation
- [ ] Create token exchange endpoint
- [ ] Handle Google OAuth callback
- [ ] Handle GitHub OAuth callback
- [ ] Store tokens securely (encrypted)

Implements [[SPEC-002]] section "Implementation Details"`,
  priority: 1,
  tags: ["auth", "oauth", "tokens"]
});
await link("ISSUE-002", "SPEC-002", "implements");
await link("ISSUE-001", "ISSUE-002", "blocks");

const issue3 = await upsert_issue({
  title: "Build OAuth callback handler and user flow",
  description: `Implement complete OAuth authentication flow.

## Tasks
- [ ] OAuth callback endpoints (/auth/:provider/callback)
- [ ] User session creation
- [ ] Profile sync from OAuth provider
- [ ] Login/logout handlers
- [ ] Redirect handling after auth

Implements [[SPEC-002]] section "Authorization Flow"`,
  priority: 1,
  tags: ["auth", "oauth", "flow"]
});
await link("ISSUE-003", "SPEC-002", "implements");
await link("ISSUE-002", "ISSUE-003", "blocks");

const issue4 = await upsert_issue({
  title: "Implement session management with Redis",
  description: `Set up session storage and management.

## Tasks
- [ ] Configure Redis connection
- [ ] Implement session store
- [ ] Session middleware
- [ ] Session expiration handling
- [ ] Session cleanup job

Implements [[SPEC-003]]`,
  priority: 1,
  tags: ["auth", "session", "redis"]
});
await link("ISSUE-004", "SPEC-003", "implements");
await link("ISSUE-002", "ISSUE-004", "blocks");

const issue5 = await upsert_issue({
  title: "Implement automatic token refresh",
  description: `Refresh expired tokens automatically.

## Tasks
- [ ] Token refresh middleware
- [ ] Detect token expiration
- [ ] Exchange refresh token for new access token
- [ ] Update stored tokens
- [ ] Handle refresh token rotation

Implements [[SPEC-002]] section "Token Storage"`,
  priority: 2,
  tags: ["auth", "oauth", "tokens"]
});
await link("ISSUE-005", "SPEC-002", "implements");
await link("ISSUE-002", "ISSUE-005", "blocks");

const issue6 = await upsert_issue({
  title: "Add OAuth security hardening (PKCE, CSRF)",
  description: `Implement security best practices.

## Tasks
- [ ] PKCE implementation (already in ISSUE-002)
- [ ] CSRF protection (state parameter)
- [ ] Rate limiting on auth endpoints
- [ ] Audit logging for auth events
- [ ] Security testing

Implements [[SPEC-004]]`,
  priority: 1,
  tags: ["auth", "security", "pkce"]
});
await link("ISSUE-006", "SPEC-004", "implements");
await link("ISSUE-003", "ISSUE-006", "blocks");

Agent responds:

Created implementation plan for SPEC-001:

Foundation (P0):
  ISSUE-001: Set up OAuth provider configuration ✓ Ready

Core OAuth Flow (P1):
  ISSUE-002: Implement OAuth token exchange (blocked by ISSUE-001)
  ISSUE-003: Build callback handler and user flow (blocked by ISSUE-002)

Session Management (P1):
  ISSUE-004: Implement session management (blocked by ISSUE-002)

Token Refresh (P2):
  ISSUE-005: Implement automatic token refresh (blocked by ISSUE-002)

Security (P1):
  ISSUE-006: Add security hardening (blocked by ISSUE-003)

Dependency graph:
  ISSUE-001 (ready)
    └─> ISSUE-002
          ├─> ISSUE-003 ──> ISSUE-006
          ├─> ISSUE-004
          └─> ISSUE-005

Start with ISSUE-001 to unblock the others.

View the plan in CLI:

sudocode ready

Output:

Ready Issues (1)

ID        Title                              Priority  Tags
────────────────────────────────────────────────────────────────
ISSUE-001  Set up OAuth provider config      P0        auth, oauth, setup

sudocode blocked

Output:

Blocked Issues (5)

ID        Title                     Blocked By
────────────────────────────────────────────────────
ISSUE-002  OAuth token exchange     ISSUE-001
ISSUE-003  OAuth callback handler   ISSUE-002
ISSUE-004  Session management       ISSUE-002
ISSUE-005  Token refresh            ISSUE-002
ISSUE-006  Security hardening       ISSUE-003

Step 5: Execute Issues

Check status:

sudocode status

Output:

Project Status

Specs: 4 total
Issues: 6 total
  - 6 open
  - 0 in_progress
  - 0 blocked
  - 0 closed

Ready: 1 issue (ISSUE-001)
Blocked: 5 issues

Execute Issue 001

Agent claims the work:

sudocode issue update ISSUE-001 --status in_progress

Agent implements the configuration:

// src/config/oauth.ts
export const oauthConfig = {
  google: {
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    redirectUri: `${process.env.APP_URL}/auth/google/callback`
  },
  github: {
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    redirectUri: `${process.env.APP_URL}/auth/github/callback`
  }
};

Create .env.example:

# .env.example
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
APP_URL=http://localhost:3000

Update README.md:

## OAuth Setup

1. **Google OAuth:**
   - Go to Google Cloud Console
   - Create OAuth 2.0 credentials
   - Add redirect URI: `http://localhost:3000/auth/google/callback`

2. **GitHub OAuth:**
   - Go to GitHub Developer Settings
   - Create new OAuth app
   - Add callback URL: `http://localhost:3000/auth/github/callback`

3. **Environment:**
   - Copy `.env.example` to `.env`
   - Fill in client IDs and secrets

Commit implementation:

git add src/config/oauth.ts .env.example README.md
git commit -m "Set up OAuth provider configuration (ISSUE-001)

- Added OAuth config for Google and GitHub
- Created .env.example with required variables
- Documented OAuth setup in README

Closes ISSUE-001
Implements SPEC-002"

Close the issue:

sudocode issue close ISSUE-001 \
  --comment "OAuth providers configured. Environment variables documented."

Sync and commit context:

sudocode sync
git add .sudocode/
git commit -m "Close ISSUE-001"

Check what’s now ready:

sudocode ready

Output:

Ready Issues (3)

ID        Title                     Priority  Tags
────────────────────────────────────────────────────────
ISSUE-002  OAuth token exchange     P1        auth, oauth, tokens
ISSUE-004  Session management       P1        auth, session, redis
ISSUE-005  Token refresh            P2        auth, oauth, tokens

Notice: ISSUE-002, ISSUE-004, and ISSUE-005 are now unblocked!

Execute Issue 002

Agent claims work:

sudocode issue update ISSUE-002 --status in_progress

Agent reviews spec:

sudocode spec show SPEC-002

While implementing, agent discovers ambiguity: The spec says “Token expiration handling” but doesn’t specify expiration times.

Step 6: Provide Feedback

Agent adds feedback to spec:

sudocode feedback add ISSUE-002 SPEC-002 \
  --content "Token expiration times not specified in spec. Industry standards recommend:
  - Access tokens: 15 minutes (short-lived)
  - Refresh tokens: 7 days (balance security and UX)

  Please clarify preferred expiration times. I'll use 15min/7d for now." \
  --type request \
  --line 42

Expected output

Created FEEDBACK-001

Feedback anchored to SPEC-002:42
  From: ISSUE-002
  Type: request

View feedback:
  sudocode feedback list --spec SPEC-002

Agent continues with reasonable defaults:

// src/services/token-manager.ts
export class TokenManager {
  private readonly ACCESS_TOKEN_TTL = 15 * 60; // 15 minutes
  private readonly REFRESH_TOKEN_TTL = 7 * 24 * 60 * 60; // 7 days

  async exchangeCodeForTokens(
    provider: 'google' | 'github',
    code: string,
    codeVerifier: string
  ): Promise<TokenPair> {
    // Exchange authorization code for tokens
    const response = await this.exchangeWithProvider(provider, code, codeVerifier);

    // Store tokens encrypted
    const tokens = {
      accessToken: response.access_token,
      refreshToken: response.refresh_token,
      expiresAt: new Date(Date.now() + this.ACCESS_TOKEN_TTL * 1000)
    };

    await this.storeTokens(userId, tokens);

    return tokens;
  }
}

Commit implementation:

git add src/services/token-manager.ts
git commit -m "Implement OAuth token exchange (ISSUE-002)

- PKCE code generation and verification
- Token exchange for Google and GitHub
- Encrypted token storage
- Using 15min/7d expiration (pending spec clarification)

Addresses ISSUE-002
Implements SPEC-002"

View feedback:

sudocode feedback list --spec SPEC-002

Output:

Feedback on SPEC-002 (1 item)

FEEDBACK-001 (request) - Line 42
  From: ISSUE-002
  Status: Open

  Token expiration times not specified in spec. Industry standards recommend:
  - Access tokens: 15 minutes (short-lived)
  - Refresh tokens: 7 days (balance security and UX)

  Please clarify preferred expiration times. I'll use 15min/7d for now.

Human reviews feedback and updates spec:

vim .sudocode/specs/oauth-2-0-integration.md

Update line 42 area:

### Token Expiration

**Access tokens:** 15 minutes
- Short-lived for security
- Minimizes risk if token is compromised
- Requires refresh mechanism

**Refresh tokens:** 7 days
- Balance between security and user experience
- Allows seamless re-authentication
- Rotation on each use (security best practice)

**Rationale:**
- Follows OAuth 2.0 security best practices (RFC 6749)
- Access token compromise has limited window
- Refresh token enables long-lived sessions without re-login

Sync and dismiss feedback:

sudocode sync --from-markdown

sudocode feedback dismiss FEEDBACK-001 \
  --comment "Spec updated with explicit expiration times based on agent recommendation"

Commit spec update:

git add .sudocode/
git commit -m "Update SPEC-002 with token expiration details

Added explicit token expiration times based on FEEDBACK-001:
- Access tokens: 15 minutes
- Refresh tokens: 7 days

Includes rationale for security/UX balance."

Step 7: Handle Dependencies and Continue

Close ISSUE-002:

sudocode issue close ISSUE-002 \
  --comment "Token exchange complete with PKCE, encrypted storage, and expiration handling"

Check what’s unblocked:

sudocode ready

Output:

Ready Issues (4)

ID        Title                         Priority
────────────────────────────────────────────────────
ISSUE-003  OAuth callback handler       P1
ISSUE-004  Session management           P1
ISSUE-005  Token refresh                P2

Notice: ISSUE-003 is now unblocked (was blocked by ISSUE-002) Continue with ISSUE-003:

sudocode issue update ISSUE-003 --status in_progress

Implement callback handlers:

// src/routes/auth.ts
import express from 'express';
import { TokenManager } from '../services/token-manager';

const router = express.Router();
const tokenManager = new TokenManager();

router.get('/auth/:provider/callback', async (req, res) => {
  const { provider } = req.params;
  const { code, state } = req.query;

  try {
    // Verify CSRF state
    if (!verifyState(state)) {
      return res.redirect('/auth/error?reason=invalid_state');
    }

    // Get code verifier from session
    const codeVerifier = req.session.codeVerifier;

    // Exchange code for tokens
    const tokens = await tokenManager.exchangeCodeForTokens(
      provider as 'google' | 'github',
      code as string,
      codeVerifier
    );

    // Fetch user profile
    const profile = await fetchUserProfile(provider, tokens.accessToken);

    // Create or update user
    const user = await upsertUser(profile);

    // Create session
    req.session.userId = user.id;
    req.session.provider = provider;

    // Redirect to dashboard
    res.redirect('/dashboard');
  } catch (error) {
    console.error('OAuth callback error:', error);
    res.redirect('/auth/error');
  }
});

export default router;

Commit and close:

git add src/routes/auth.ts
git commit -m "Implement OAuth callback handler (ISSUE-003)

- Handle Google and GitHub callbacks
- CSRF state verification
- User profile sync
- Session creation
- Error handling

Closes ISSUE-003
Implements SPEC-002"

sudocode issue close ISSUE-003

Continue pattern for remaining issues… (ISSUE-004: Session management, ISSUE-005: Token refresh, ISSUE-006: Security)

Step 8: Track Progress

View current status:

sudocode status

Output:

Project Status

Specs: 4 total
Issues: 6 total
  - 2 open (ISSUE-005, ISSUE-006)
  - 1 in_progress (ISSUE-004)
  - 0 blocked
  - 3 closed

Ready: 2 issues
Blocked: 0 issues

View detailed stats:

sudocode stats

Output:

Project Statistics

Specs: 4 total

Issues: 6 total
  By status: 2 open, 1 in_progress, 3 closed
  Ready: 2
  Blocked: 0

Relationships: 10 total
  6 implements, 4 blocks

Recent activity (7 days):
  2 specs updated
  6 issues updated
  3 issues closed

Step 9: Complete Remaining Work

Finish ISSUE-004 (Session Management):

# Implementation...
sudocode issue close ISSUE-004

Finish ISSUE-005 (Token Refresh):

# Implementation...
sudocode issue close ISSUE-005

Finish ISSUE-006 (Security Hardening):

# Implementation...
sudocode issue close ISSUE-006

Final status:

sudocode status

Output:

Project Status

Specs: 4 total
Issues: 6 total
  - 0 open
  - 0 in_progress
  - 0 blocked
  - 6 closed ✓

All work complete!

Step 10: Verify Against Spec

Review SPEC-001:

sudocode spec show SPEC-001

Check off success criteria:

## Success Criteria
- [x] Users can authenticate with Google
- [x] Users can authenticate with GitHub
- [x] Tokens refresh automatically before expiration
- [x] No OWASP Top 10 vulnerabilities
- [x] Auth flow completes in < 3 seconds
- [x] 100% test coverage on auth flows

Update spec status:

sudocode spec update SPEC-001 --status completed

Final commit:

sudocode sync
git add .sudocode/
git commit -m "Mark SPEC-001 as completed

All authentication system requirements implemented:
- OAuth 2.0 with Google and GitHub
- Session management with Redis
- Automatic token refresh
- Security hardening (PKCE, CSRF, rate limiting)

All issues closed:
- ISSUE-001: OAuth setup
- ISSUE-002: Token exchange
- ISSUE-003: Callback handler
- ISSUE-004: Session management
- ISSUE-005: Token refresh
- ISSUE-006: Security hardening"

Git History

View the complete history:

git log --oneline --graph

Output:

* a3f5d21 Mark SPEC-001 as completed
* 8c7b456 Implement security hardening (ISSUE-006)
* 5d9e123 Implement token refresh (ISSUE-005)
* 4a2c789 Implement session management (ISSUE-004)
* 7f1b234 Implement OAuth callback handler (ISSUE-003)
* 2e8d456 Close ISSUE-002
* 9b3c789 Implement OAuth token exchange (ISSUE-002)
* 1a5f234 Close ISSUE-001
* 6d4e567 Set up OAuth provider configuration (ISSUE-001)
* 3c2b890 Update SPEC-002 with token expiration details
* 8a7f123 Add OAuth and session sub-specs (SPEC-002, SPEC-003, SPEC-004)
* 5e9c234 Add authentication system spec (SPEC-001)
* 2f1d567 Initialize sudocode

Notice: Every commit includes both code and context changes, creating a complete history.

Example Pull Request

When creating a PR, reference the specs and issues:

## Implement User Authentication System

Implements **SPEC-001**: User Authentication System

### Overview
Complete OAuth 2.0 authentication system with Google and GitHub providers,
session management, automatic token refresh, and security hardening.

### Implementation Details

**Sub-specs:**
- [[SPEC-002]] OAuth 2.0 Integration
- [[SPEC-003]] Session Management
- [[SPEC-004]] Security Hardening

**Issues closed:**
- ISSUE-001: Set up OAuth provider configuration
- ISSUE-002: Implement OAuth token exchange
- ISSUE-003: Build OAuth callback handler
- ISSUE-004: Implement session management
- ISSUE-005: Implement automatic token refresh
- ISSUE-006: Add security hardening

### Security Features
- PKCE for all OAuth flows
- CSRF protection via state parameter
- Token encryption at rest
- httpOnly cookies for sessions
- Rate limiting on auth endpoints
- Comprehensive audit logging

### Testing
- 100% coverage on authentication flows
- Integration tests for Google and GitHub OAuth
- Security testing against OWASP Top 10

### Performance
- Auth flow completes in ~2s (well under 3s requirement)
- Token refresh is automatic and transparent

### Documentation
- OAuth setup instructions in README
- Environment variable documentation
- API endpoints documented

Best Practices Demonstrated

Spec refinement through feedback

What we did:

Agent discovered missing expiration times
Provided anchored feedback with recommendation
Human updated spec with explicit values

Why it matters:

Specs improve based on implementation reality
Ambiguities surface early
Knowledge compounds in version control

Hierarchical organization

What we did:

High-level SPEC-001
Detailed sub-specs (SPEC-002, SPEC-003, SPEC-004)
Issues implement specific sub-specs

Why it matters:

Allows parallel work on independent pieces
Focused reviews
Incremental delivery possible

Explicit dependencies

What we did:

Used blocks relationships
Foundation work (ISSUE-001) blocks everything else
Clear dependency graph

Why it matters:

Automatic ready work detection
Prevents blocking on unavailable work
Enables parallel execution

Context with code

What we did:

Every code commit includes sudocode changes
Commit messages reference specs and issues
Complete git history

Why it matters:

Context travels with code through branches
Code review includes design decisions
History explains why, not just what

Agent feedback timing

What we did:

Agent provided feedback immediately on discovery
Continued with reasonable assumption
Didn’t block waiting for clarification

Why it matters:

Keeps agent unblocked
Human reviews feedback asynchronously
Iteration continues smoothly

Progressive status tracking

What we did:

Used sudocode status to monitor progress
sudocode ready to find next work
sudocode blocked to identify bottlenecks

Why it matters:

Clear visibility into project state
Easy to identify what needs attention
Metrics for project health

What You Learned

Spec Creation

Write effective specifications
Organize hierarchically
Define success criteria
Leave open questions

Implementation Planning

Break specs into issues
Model dependencies
Use implements relationships
Prioritize work

Execution

Query ready work
Claim issues
Commit code + context together
Close with summaries

Feedback Loop

Surface ambiguities early
Anchor feedback to lines
Continue with assumptions
Iterate on specs

Dependency Management

Use blocks relationships
Track blockers
Unblock automatically
Enable parallel work

Progress Tracking

Monitor with status
Find work with ready
Identify bottlenecks with blocked
Measure with stats

Common Patterns

Pattern: Foundation First

Always start with foundation/setup work:

Configuration (ISSUE-001)
Core functionality (ISSUE-002, ISSUE-003)
Enhancements (ISSUE-005)
Polish (ISSUE-006)

Specs improve through implementation:

Start with high-level requirements
Add details as questions arise
Update based on learnings
Never “done” - always evolving

Pattern: Parallel Execution

After foundation, multiple agents can work simultaneously:

ISSUE-004 (session) and ISSUE-005 (refresh) both depend on ISSUE-002
Once ISSUE-002 completes, both become ready
Agents can work independently

Pattern: Commit Granularity

One commit per issue completion:

Includes both code and context changes
Clear commit message referencing issue
Easy to review
Easy to revert if needed

Troubleshooting

Issue shows as blocked but blocker is closed

Cause: Database not synced after closing blockerSolution:

sudocode sync
sudocode ready  # Should now show issue

Feedback anchor shows as stale

Cause: Spec content moved, anchor needs relocationSolution:

sudocode feedback stale  # Find stale feedback
sudocode feedback relocate FEEDBACK-001 --line 50  # Relocate

Can't find spec or issue after git pull

Cause: JSONL imported but not synced to markdownSolution:

sudocode sync --to-markdown

Ready query returns nothing but work exists

Cause: All open issues are blockedSolution:

sudocode blocked  # Find what's blocking
# Work on blockers first

Next Steps

Try it yourself

Follow this tutorial with your own feature

Explore advanced features

Multi-agent collaboration
Git branching with context
Feedback workflows
Graph visualization

Set up MCP integration

Enable AI agents to autonomously execute this workflow

Customize for your team

Adapt the workflow to your development process

Spec-Driven Development

Complete SDD workflow guide

CLI Reference

All CLI commands

MCP Workflows

AI agent workflow examples

Feedback System

Anchored feedback details

Relationships

Dependency modeling

Storage Model

How data flows

Summary

You’ve completed a full feature implementation using spec-driven development: ✅ Created hierarchical specifications ✅ Planned implementation with AI agent ✅ Executed work in dependency order ✅ Provided feedback to refine specs ✅ Tracked progress throughout ✅ Committed context with code ✅ Completed all work with full traceability Key takeaway: Context is durable, queryable, and travels with your code. Specifications evolve through bidirectional feedback, and dependencies enable autonomous work selection. Ready to build your next feature with sudocode!

Getting Started

Core Concepts

Examples & Tutorials

​Tutorial Overview

​Step 1: Initialize Project

​Step 2: Create High-Level Specification

​Step 3: Break Down into Sub-Specs

​Token Storage

​Configuration

​Error Handling

​Step 4: Plan Implementation with AI Agent

​Step 5: Execute Issues

​Execute Issue 001

​Execute Issue 002

​Step 6: Provide Feedback

​Step 7: Handle Dependencies and Continue

​Step 8: Track Progress

​Step 9: Complete Remaining Work

​Step 10: Verify Against Spec

​Git History

​Example Pull Request

​Best Practices Demonstrated

​What You Learned

Spec Creation

Implementation Planning

Execution

Feedback Loop

Dependency Management

Progress Tracking

​Common Patterns

​Pattern: Foundation First

​Pattern: Continuous Refinement

​Pattern: Parallel Execution

​Pattern: Commit Granularity

​Troubleshooting

​Next Steps

​Related Documentation

Spec-Driven Development

CLI Reference

MCP Workflows

Feedback System

Relationships

Storage Model

​Summary

Tutorial Overview

Step 1: Initialize Project

Step 2: Create High-Level Specification

Step 3: Break Down into Sub-Specs

Token Storage

Configuration

Error Handling

Step 4: Plan Implementation with AI Agent

Step 5: Execute Issues

Execute Issue 001

Execute Issue 002

Step 6: Provide Feedback

Step 7: Handle Dependencies and Continue

Step 8: Track Progress

Step 9: Complete Remaining Work

Step 10: Verify Against Spec

Git History

Example Pull Request

Best Practices Demonstrated

What You Learned

Common Patterns

Pattern: Foundation First

Pattern: Continuous Refinement

Pattern: Parallel Execution

Pattern: Commit Granularity

Troubleshooting

Next Steps

Related Documentation

Summary