Professional Coding Skill

Version: 1.0.0
Author: openrouter-coder
Created: 2026-02-02
Name: professional-coding
Description: Token-optimized professional coding workflow with agent delegation, GitHub automation, and quality assurance

Overview

This skill defines a production-grade coding workflow that:

• •✅ Minimizes token costs (Main agent max 25k tokens/project)
• •✅ Delegates work to specialized agents (coder, long-context, git-agent)
• •✅ Automates GitHub integration (repo creation, PR workflow)
• •✅ Enforces quality gates (mandatory review, testing, bug fixes)
• •✅ Follows professional standards (documentation, error handling, type hints)

Target audience: Main agent (Claude Sonnet) coordinating complex coding projects
Related: OPTIMIZED_CODING_WORKFLOW.md, github skill, AGENTS.md

Token Optimization Strategy

Main Agent Constraints

• •Maximum budget: 25,000 tokens per project
• •Forbidden actions: Reading code files, analyzing implementations, reviewing code directly
• •Allowed actions: Reading JSON session results, parsing responses, delegating tasks

Token Allocation by Phase

Cost Comparison

• •Optimized workflow: $0.44 per project (this skill)
• •Suboptimal workflow: $1.50 per project (Main doing everything)
• •Savings: 71% reduction

Agent Strategy

Agent Roles & Selection

When to Use Each Agent

openrouter-coder:

• •Writing new code (<500 LOC per task)
• •Refactoring existing functions
• •Bug fixes
• •Adding features to existing modules

long-context:

• •Analyzing large codebases (>10 files)
• •Architectural planning
• •Code review (security, performance, style)
• •Documentation generation

git-agent:

• •Git operations (commit, push, branch, merge)
• •GitHub API calls (create repo, PR, issues)
• •CI/CD integration
• •Release management

openrouter-reasoner:

• •Algorithm design
• •Performance optimization
• •Complex business logic
• •Data structure decisions

Parallel Delegation

Main can spawn multiple agents simultaneously for independent tasks:

// Example: Parallel implementation
sessions_spawn("openrouter-coder", { task: "Implement module A", files: ["a.py"] })
sessions_spawn("openrouter-coder", { task: "Implement module B", files: ["b.py"] })
sessions_spawn("openrouter-coder", { task: "Implement module C", files: ["c.py"] })

Result: 3x faster execution, same cost

GitHub Integration

New Project Workflow (Automatic)

When: Creating a brand new tool/project

Steps:

1. •Code implemented by openrouter-coder
2. •Automatically create GitHub repo (TAPANIBOT org, private)
3. •Automatically push code (no user prompt needed)
4. •Notify user with repo URL

Why: Version control is mandatory. Don't wait for user to ask.

Agent: git-agent

Example:

# Create repo
~/clawd/skills/github/scripts/gh-api.sh repos/create project-name "Description" private

# Push code
cd ~/path/to/project
git init
git add .
git commit -m "Initial commit: Brief description"
git remote add origin https://tapanibot308:TOKEN@github.com/TAPANIBOT/project-name.git
git push -u origin main

Existing Project Workflow (PR-based)

When: Modifying existing codebase

Steps:

1. •Create feature branch (feature/description)
2. •Make changes
3. •Create Pull Request (via iterative-dev-framework)
4. •CI/CD runs tests
5. •Claude Gate reviews (quality gates)
6. •Auto-merge if approved

Agent: git-agent

Benefits:

• •Code review history
• •Rollback capability
• •CI/CD integration
• •Team collaboration

Quality Assurance

Mandatory Review Phase

Every project must go through code review by long-context agent.

Review checklist:

1. •Functionality: Does code do what was requested?
2. •Security: Input validation, no hardcoded secrets, no SQL injection
3. •Performance: Efficient algorithms, no obvious bottlenecks
4. •Style: Consistent formatting, clear naming, proper comments
5. •Documentation: README, docstrings, usage examples
6. •Testing: Unit tests present, edge cases covered

Output: JSON with issues categorized by severity (critical/major/minor)

Bug Fix Iterations

Process:

1. •Review identifies issues
2. •Main categorizes severity
3. •Critical issues: Ask user for approval
4. •Non-critical issues: Delegate fix to openrouter-coder automatically
5. •Re-review after fixes
6. •Repeat until no critical issues remain

Maximum iterations: 3 (prevent infinite loops)

Testing Strategy

Required tests:

• •Unit tests: Core functions, edge cases
• •Integration tests: Module interactions
• •E2E tests: Full workflow (if applicable)

Coverage target: 80% (pragmatic, not dogmatic)

Frameworks:

• •Python: pytest
• •JavaScript: Jest/Vitest
• •TypeScript: Jest/Vitest
• •Go: built-in testing

Best Practices

Documentation Standards

README.md (mandatory):

# Project Name

## Description
What does this do?

## Installation
pip install -r requirements.txt

## Usage
python main.py --help

## Examples
See examples/ folder

## License
MIT

Code docstrings (mandatory for public functions):

def process_data(input: str, max_length: int = 100) -> dict:
    """
    Process input data and return structured result.
    
    Args:
        input: Raw text input
        max_length: Maximum length of processed output
        
    Returns:
        dict with 'status', 'data', 'errors' keys
        
    Raises:
        ValueError: If input is empty or invalid
    """
    pass

Error Handling

Always use:

• •Try/except blocks for external operations (file I/O, network, API calls)
• •Specific exceptions (not bare except)
• •Meaningful error messages
• •Logging (not just print statements)

Example:

import logging

logger = logging.getLogger(__name__)

try:
    result = api_call()
except requests.HTTPError as e:
    logger.error(f"API call failed: {e}")
    raise
except requests.Timeout:
    logger.warning("API timeout, retrying...")
    result = retry_api_call()

Type Hints (Python)

Mandatory for:

• •Function signatures
• •Class attributes
• •Complex data structures

Example:

from typing import List, Dict, Optional

def analyze_data(
    data: List[Dict[str, any]],
    threshold: float = 0.5
) -> Optional[Dict[str, float]]:
    pass

Modular Architecture

Principles:

• •Separation of concerns: One module = one responsibility
• •DRY (Don't Repeat Yourself): Extract common code
• •SOLID principles: Especially Single Responsibility
• •Small functions: <50 LOC per function

Project structure:

project/
├── README.md
├── requirements.txt
├── setup.py
├── src/
│   ├── __init__.py
│   ├── core.py       # Core logic
│   ├── utils.py      # Helper functions
│   └── api.py        # External interfaces
├── tests/
│   ├── test_core.py
│   └── test_api.py
└── examples/
    └── basic_usage.py

Decision Tree

USER REQUEST: "Implement feature X"
    ↓
MAIN: Read AGENTS.md (3k tokens, cached)
    ↓
    ┌────────────────────────────────────────────┐
    │  Assess Project Complexity                 │
    └────────────────────────────────────────────┘
              ↓
    ┌─────────┬──────────────┬────────────────┐
    │         │              │                │
    │ TRIVIAL │  MEDIUM      │  COMPLEX       │
    │ <20 LOC │  20-100 LOC  │  >100 LOC      │
    │         │              │                │
    └────┬────┴──────┬───────┴────────┬───────┘
         │           │                │
         ↓           ↓                ↓
    ┌─────────┐ ┌──────────┐    ┌──────────┐
    │  CODER  │ │ PLANNER  │    │ PLANNER  │
    │  direct │ │ (long-   │    │ (long-   │
    │  impl.  │ │ context) │    │ context) │
    └────┬────┘ └────┬─────┘    └────┬─────┘
         │           │                │
         ↓           ↓                ↓
    ┌─────────┐ ┌──────────┐    ┌──────────┐
    │   GIT   │ │  CODER   │    │ CODER(s) │
    │         │ │  (N=1-3) │    │ parallel │
    └────┬────┘ └────┬─────┘    │ (N=3-10) │
         │           │           └────┬─────┘
         │           ↓                ↓
         │      ┌──────────┐    ┌──────────┐
         │      │ REVIEWER │    │ REVIEWER │
         │      │ (long-   │    │ (long-   │
         │      │ context) │    │ context) │
         │      └────┬─────┘    └────┬─────┘
         │           │                │
         │           ↓                ↓
         │      ┌──────────┐    ┌──────────┐
         │      │ BUG FIXER│    │BUG FIXER │
         │      │ if needed│    │ 1-3 iters│
         │      └────┬─────┘    └────┬─────┘
         │           │                │
         │           ↓                ↓
         │      ┌──────────┐    ┌──────────┐
         │      │   GIT    │    │   GIT    │
         │      └────┬─────┘    └────┬─────┘
         │           │                │
         └───────────┴────────────────┘
                     ↓
            ┌────────────────┐
            │ GitHub Action  │
            │ • New project: │
            │   Create repo  │
            │   + push       │
            │ • Existing:    │
            │   Create PR    │
            └────────┬───────┘
                     ↓
            ┌────────────────┐
            │  User Report   │
            │ "✅ Done!"     │
            │ Repo/PR link   │
            └────────────────┘

Metrics & Monitoring

Token Metrics

Track per project:

• •Main tokens used
• •Agent tokens used
• •Total cost
• •Savings vs. suboptimal workflow

Log format:

{
  "project": "riistakamera-annotator",
  "date": "2026-02-02",
  "main_tokens": 23500,
  "agent_tokens": 127000,
  "total_cost": 0.42,
  "phases": {
    "planning": {"main": 5000, "agent": 25000},
    "implementation": {"main": 8000, "agent": 60000},
    "review": {"main": 3000, "agent": 20000},
    "fixes": {"main": 2000, "agent": 12000},
    "git": {"main": 3000, "agent": 10000},
    "summary": {"main": 2500, "agent": 0}
  }
}

Time Estimates

Quality Indicators

Success criteria:

• •✅ All critical issues resolved
• •✅ Tests passing
• •✅ Documentation complete
• •✅ Code reviewed
• •✅ Pushed to GitHub

Warning signs:

• •⚠️ >3 review iterations
• •⚠️ >40k Main tokens used
• •⚠️ No tests written
• •⚠️ Critical security issues

Examples

Example 1: Trivial Project (CLI Tool)

Request: "Create a CLI tool that converts JSON to YAML"

Complexity: Trivial (<20 LOC)

Workflow:

1. •Main: Delegate to openrouter-coder directly
2. •Coder: Implement in single file (15 LOC)
3. •Main: Quick sanity check (1k tokens)
4. •Main: Delegate to git-agent (commit + push)
5. •Main: Report to user

Tokens: 6k @ Main, 10k @ coder, 5k @ git-agent
Cost: $0.05
Duration: 1 minute

Output:

✅ Project complete!
Repository: https://github.com/TAPANIBOT/json-to-yaml
Commit: abc123f

Example 2: Medium Project (Web Scraper)

Request: "Create a web scraper for extracting product data from e-commerce sites"

Complexity: Medium (60 LOC, 3 files)

Workflow:

1. •Main: Delegate planning to long-context
2. •Long-context: Returns JSON plan (3 modules: scraper.py, parser.py, main.py)
3. •Main: Delegates 3 parallel coder tasks
4. •Coders: Implement modules (15 min total, runs in parallel)
5. •Main: Delegate review to long-context
6. •Long-context: Identifies 2 minor issues (no error handling, missing docstrings)
7. •Main: Auto-fix by delegating to coder
8. •Main: Delegate git operations
9. •Main: Report to user

Tokens: 16k @ Main, 85k @ agents
Cost: $0.30
Duration: 5 minutes

Output:

✅ Project complete!
Repository: https://github.com/TAPANIBOT/ecommerce-scraper
Files: scraper.py, parser.py, main.py, requirements.txt, README.md
Tests: 8 unit tests (coverage: 85%)
Commit: def456a

Example 3: Complex Project (REST API with Database)

Request: "Create a REST API for task management with SQLite database"

Complexity: Complex (300 LOC, 8 files)

Workflow:

1. •Main: Delegate planning to long-context
2. •Long-context: Returns detailed JSON plan (architecture, modules, database schema)
3. •Main: Delegates 8 parallel coder tasks (models, routes, db, auth, tests, docs)
4. •Coders: Implement modules (20 min total, parallel execution)
5. •Main: Delegate review to long-context
6. •Long-context: Identifies 5 issues (1 critical: no SQL injection protection)
7. •Main: Ask user about critical issue
8. •User: "Fix it"
9. •Main: Delegate fix to coder
10. •Main: Re-review (long-context confirms fix)
11. •Main: Delegate git operations + PR creation
12. •Main: Report to user

Tokens: 24k @ Main, 180k @ agents
Cost: $0.80
Duration: 20 minutes

Output:

✅ Project complete!
Repository: https://github.com/TAPANIBOT/task-manager-api
Pull Request: #1 (CI running...)
Files: 8 modules, 15 tests (coverage: 82%)
Security: ✅ SQL injection protected
Documentation: ✅ API docs + README
Next: Review PR and merge when CI passes

Integration with Existing Workflows

iterative-dev-framework

This skill is designed to work with TAPANIBOT/iterative-dev-framework:

• •.clawdbot/policy.yml defines agent tiers
• •Cheap agents (Devstral, Gemini) used by default
• •Medium tier only for >30k chars or 2+ cheap failures
• •Main (Claude Sonnet) acts as Gate reviewer

GitHub Skill

Delegates all GitHub operations to github skill:

• •Repo creation: gh-api.sh repos/create
• •PR creation: gh-api.sh pr/create
• •Issue management: gh-api.sh issues/create

Memory System

Uses daily logs (memory/YYYY-MM-DD.md) to track:

• •Token usage per project
• •Quality issues encountered
• •Lessons learned
• •Cost optimization opportunities

Limitations & Warnings

Current Limitations

• •No GUI development: Focus on CLI, APIs, libraries
• •No large refactoring: >1000 LOC changes should be split
• •No real-time systems: No websockets, no streaming
• •Language support: Best with Python, JavaScript, TypeScript, Go

Security Warnings

• •⚠️ Never use openrouter-reasoner for confidential data (Chinese model)
• •⚠️ Always review generated secrets/tokens (ensure no hardcoding)
• •⚠️ Check dependencies for vulnerabilities (use pip audit, npm audit)

Cost Warnings

• •⚠️ Long-context can be expensive for huge codebases (>100 files)
• •⚠️ Parallel coder spawns multiply costs (10 parallel = 10x cost)
• •⚠️ Review iterations add up (3 iterations = 60k extra tokens)

References

• •OPTIMIZED_CODING_WORKFLOW.md - Detailed token budget breakdown
• •AGENTS.md - Agent capabilities and constraints
• •github/SKILL.md - GitHub integration details
• •references/workflows.md - Step-by-step workflows
• •references/quality-gates.md - Quality criteria

Next Steps:

1. •Read workflow details in references/workflows.md
2. •Review quality gates in references/quality-gates.md
3. •Start with trivial projects to test workflow
4. •Track token usage and optimize