swe-developing-applications-common

name	swe-developing-applications-common
description	Common software development workflow patterns shared across all language developer agents

Common Software Development Workflow

This Skill provides universal development workflow guidance shared across all language-specific developer agents in the Open Sharia Enterprise platform.

Purpose

Use this Skill when:

• Developing applications in any programming language
• Working within the Nx monorepo structure
• Following platform git workflow standards
• Understanding tool usage patterns for development
• Leveraging platform automation

Tool Usage for Developers

Standard Developer Tools: read, write, edit, glob, grep, bash

Tool Purposes:

• read: Load source files and documentation for analysis
• write: Create new source files and test files
• edit: Modify existing code files
• glob: Discover files matching patterns
• grep: Search code patterns across files
• bash: Execute language tooling, run tests, git operations

Tool Selection Guidance:

• Use read for understanding existing code and documentation
• Use write for creating new files from scratch
• Use edit for modifying existing files (preferred over write for changes)
• Use glob for file discovery (NOT bash find)
• Use grep for content search (NOT bash grep)
• Use bash for running compilers, test runners, build tools, git commands

Nx Monorepo Integration

Repository Structure

This platform uses Nx for monorepo management with clear separation of concerns:

Apps (apps/[app-name]):

• Deployable applications
• Import libraries but never export
• Each independently deployable
• Never import other apps

Libraries (libs/[lib-name]):

• Reusable code modules
• Flat structure (no nesting)
• Can import other libraries (no circular dependencies)
• Naming convention: [language]-[name] (e.g., ts-utils, java-common)

Common Nx Commands

All target names follow Nx Target Standards. Use canonical names: dev (not serve), test:quick (not test), start (not serve for production).

Development:

nx dev [project-name]       # Start development server (use 'dev', not 'serve')
nx start [project-name]     # Start production server (use 'start', not 'serve')

Building:

nx build [project-name]     # Build specific project
nx affected -t build        # Build only affected projects

Testing:

nx run [project-name]:test:quick        # Fast pre-push quality gate (mandatory for all projects)
nx run [project-name]:test:unit         # Isolated unit tests
nx run [project-name]:test:integration  # Tests requiring external services
nx run [project-name]:test:e2e          # End-to-end tests (run via scheduled cron, not pre-push)
nx affected -t test:quick               # Run quality gate for affected projects

Analysis:

nx graph                   # Visualize dependencies
nx affected:graph          # Show affected dependency graph

Affected Commands Philosophy:

• After making changes, use nx affected:* commands
• Only builds/tests projects impacted by your changes
• Efficient in large monorepo (don't rebuild everything)

Monorepo Best Practices

1. Keep libraries focused: Each library should have single responsibility
2. Avoid circular dependencies: Libraries form directed acyclic graph (DAG)
3. Use affected commands: Leverage Nx's smart rebuilding
4. Apps never depend on apps: Only libraries are shared
5. Test at library level: Unit test libraries, integration test apps

Git Workflow

Trunk Based Development

Core Principle: All development happens on main branch

Branch Strategy:

• Default branch: main (all development work)
• Environment branches: prod-* (deployment only, never commit directly)
• No feature branches: Commit small changes frequently to main
• No long-lived branches: Keep changes integrated

Why Trunk Based Development?

• Reduces merge conflicts (no long-lived branches)
• Encourages small, incremental changes
• Faster feedback loop
• Simplifies deployment pipeline

Conventional Commits Format

Pattern: <type>(<scope>): <description>

Required Format:

• type: Category of change (see types below)
• scope: Optional but recommended (component/module affected)
• description: Imperative mood ("add" not "added"), no period at end

Commit Types:

• feat: New feature or capability
• fix: Bug fix
• docs: Documentation changes only
• style: Code style changes (formatting, no logic change)
• refactor: Code restructuring (no feature change, no bug fix)
• perf: Performance improvements
• test: Adding or updating tests
• chore: Build process, tooling, dependencies
• ci: CI/CD pipeline changes
• revert: Reverting previous commit

Examples:

feat(auth): add OAuth2 login support
fix(api): handle null response in user endpoint
docs(readme): update installation instructions
refactor(utils): simplify date formatting logic
test(auth): add integration tests for login flow

Split Commits by Domain:

• Different types → separate commits
• Different scopes → separate commits
• Different concerns → separate commits

Example (wrong):

git commit -m "feat(auth): add login + fix(api): fix bug + docs: update readme"

Example (correct):

git commit -m "feat(auth): add OAuth2 login support"
git commit -m "fix(api): handle null response in user endpoint"
git commit -m "docs(readme): update installation instructions"

Git Discipline

CRITICAL: Never stage or commit unless explicitly instructed by user

Default Behavior:

• Do NOT run git add automatically
• Do NOT run git commit automatically
• User must explicitly request commits

Commit Permission:

• One-time only (not continuous)
• User says "commit these changes" → you commit once
• User does NOT say "commit everything I ask you to do" → don't assume

Why This Matters:

• User controls git history
• Prevents unwanted commits
• User decides commit boundaries
• Respects user's workflow preferences

Pre-commit Automation

Automated Quality Gates

When code files are modified, Husky + lint-staged automatically run:

Pre-commit Hooks:

1. Format with Prettier: Automatically formats staged files
2. Lint markdown: Validates markdown files with markdownlint
3. Validate links: Checks markdown links aren't broken
4. Auto-stage changes: Automatically stages formatting fixes

Commit-msg Hook:

• Validate commit format: Ensures Conventional Commits compliance
• Blocks invalid commits: Prevents commit if format wrong

Pre-push Hook:

• Run test:quick for affected projects: Executes the fast quality gate (nx affected -t test:quick) — this is the canonical pre-push check. Every project must expose a test:quick target.
• Markdown linting: Final markdown quality check

Note: test:e2e does NOT run in the pre-push hook. It runs on a scheduled GitHub Actions cron job (twice daily per workflow) targeting each *-e2e project. See Nx Target Standards for the full execution model.

Trust the Automation

Philosophy: Focus on code quality, let automation handle style

What This Means:

• Don't manually format code (Prettier handles it)
• Don't worry about markdown formatting (automated)
• Don't manually check links (automation validates)
• Trust that tests will run before push

If Pre-commit Hook Fails:

1. Read the error message carefully
2. Fix the reported issue
3. Re-stage files if needed
4. Commit again (creates NEW commit, don't amend unless asked)

Common Failures:

• Markdown linting: Run npm run lint:md:fix to auto-fix
• Test failures: Fix the failing test, re-commit
• Link validation: Fix broken links, re-commit
• Commit message format: Rewrite commit message following Conventional Commits

Development Environment Setup

Before implementing any changes, ensure the development environment is ready. This prevents wasted time on toolchain issues mid-implementation.

Quick Verification

# Verify all tools are installed and at correct versions
npm run doctor

# If tools are missing, auto-install them
npm run doctor -- --fix

# Preview what would be installed (dry run)
npm run doctor -- --fix --dry-run

# Check only core tools (git, volta, node, npm, go, docker, jq)
npm run doctor -- --scope minimal

Environment File Management (rhino-cli)

The repository uses rhino-cli for environment file management:

# Initialize .env files from .env.example templates
CGO_ENABLED=0 go run -C apps/rhino-cli main.go env init

# Backup current .env files
CGO_ENABLED=0 go run -C apps/rhino-cli main.go env backup

# Restore .env files from backup
CGO_ENABLED=0 go run -C apps/rhino-cli main.go env restore --force

# Restore including config files (AI tool settings, Docker overrides, etc.)
CGO_ENABLED=0 go run -C apps/rhino-cli main.go env restore --force --include-config

When to Run Environment Setup

• Immediately after creating or entering a git worktree — run BOTH npm install AND npm run doctor -- --fix in the root repository worktree, in that order. This is a mandatory two-step init; the postinstall hook's implicit doctor || true does NOT substitute for the explicit doctor --fix call. See Worktree Toolchain Initialization
• Before starting any implementation work — verify tools and env files are ready
• After pulling changes that modify package.json, go.mod, .tool-versions, or other version config
• After switching between projects that use different toolchains
• When any build/test/lint command fails with a "not found" or version error — run npm run doctor first

Full Setup Guide

For complete step-by-step environment setup (new machine, fresh OS, or broken toolchain), see: Development Environment Setup Workflow

Development Workflow Pattern

Standard 6-Step Workflow

All language developers follow this pattern:

1. Requirements Analysis: Understand functional and technical requirements
2. Design: Apply appropriate patterns and platform architecture
3. Implementation (TDD): Write failing test first, then minimum code to pass, then refactor
4. Test Coverage: Comprehensive unit, integration, and E2E tests — all written test-first
5. Code Review: Self-review against coding standards
6. Documentation: Update relevant docs and code comments

TDD Mandate: Red→Green→Refactor

Every code change follows this cycle — no exceptions:

1. Red — Write a failing test that captures the desired behavior. Run it and confirm it fails for the right reason (not a syntax error).
2. Green — Write the minimum code to make the test pass. Do not add behavior beyond what the test requires.
3. Refactor — With all tests green, improve the implementation. Tests must stay green throughout.

# RED: write failing test
nx run my-project:test:unit   # FAIL — function not defined

# GREEN: implement minimum to pass
nx run my-project:test:unit   # PASS

# REFACTOR: clean up; verify still green
nx run my-project:test:unit   # PASS

Commit each phase separately (TDD order):

git commit -m "test(auth): add failing email validation test"
git commit -m "feat(auth): implement email validation"
git commit -m "refactor(auth): extract regex constant"

See: Test-Driven Development Convention for the full mandate, mini-TDD cycles, and how TDD applies to plan delivery checklists.

Implementation Philosophy

Make it work → Make it right → Make it fast — with TDD driving each stage:

1. Make it work (Red→Green): Write failing test, then minimum implementation to pass
2. Make it right (Refactor): With tests green, refactor for clarity; follow standards; eliminate duplication
3. Make it fast: Optimize only when measurements prove it necessary; keep tests green

Avoid:

• Premature optimization (fast before right)
• Over-engineering (complex before simple)
• Implementation before tests (tests-after-the-fact prove code exists, not correctness)

Reference Documentation Patterns

Standard Project Documentation

All language developers reference:

• CLAUDE.md: Primary guidance for all agents
• Monorepo Structure: Nx workspace organization
• Commit Messages Convention: Conventional Commits detailed guide
• Code Quality Convention: Git hooks and automation
• Trunk Based Development: Git workflow philosophy
• Development Environment Setup: Complete toolchain setup (doctor, rhino-cli env, all language runtimes)

Language-Specific Documentation

Each language has authoritative coding standards in:

docs/explanation/software-engineering/programming-languages/[language]/README.md

Examples:

• TypeScript: docs/explanation/software-engineering/programming-languages/typescript/README.md
• Java: docs/explanation/software-engineering/programming-languages/java/README.md
• Python: docs/explanation/software-engineering/programming-languages/python/README.md
• Elixir: docs/explanation/software-engineering/programming-languages/elixir/README.md
• Go: docs/explanation/software-engineering/programming-languages/golang/README.md

Each language README covers:

1. Language idioms and patterns
2. Best practices for clean code
3. Anti-patterns to avoid
4. Framework-specific guidance
5. Testing strategies

Related Conventions

Workflow Conventions:

• Test-Driven Development Convention - Red→Green→Refactor mandate — write failing test before any production code
• Trunk Based Development - Git workflow details (all development targets main; see Plans Organization Convention §Delivery Mode for how a plan reaches main — worktree-to-pr is the default)
• PR Merge Protocol - [AI] merges by default once the five hardened preconditions hold; a [HUMAN] merge gate is an explicit per-plan opt-in; all quality gates must pass before merge
• Commit Messages Convention - Conventional Commits specification
• Implementation Workflow - Make it work → right → fast (TDD drives each stage)

Quality Conventions:

• Code Quality Convention - Git hooks, linting, formatting
• Manual Behavioral Verification - Playwright MCP for UI, curl for API testing
• Feature Change Completeness - Specs, contracts, and tests must update with every feature change
• CI Blocker Resolution - Preexisting CI failures must be investigated and fixed, never bypassed
• Reproducible Environments - Volta, package-lock.json

Architecture Conventions:

• Monorepo Structure Reference - Nx workspace organization
• Nx Target Standards - Canonical target names, mandatory targets per project type, caching rules
• Functional Programming - FP principles across languages

Related Skills

Language-specific skills provide deep expertise for each language:

• swe-programming-typescript - TypeScript idioms, patterns, frameworks
• swe-programming-java - Java idioms, patterns, frameworks
• swe-programming-python - Python idioms, patterns, frameworks
• swe-programming-elixir - Elixir idioms, OTP patterns, Phoenix
• swe-programming-golang - Go idioms, patterns, frameworks

---

Note: This Skill provides universal workflow guidance. Language-specific development patterns are in dedicated language skills.