Software Project Development Master Skill

This skill defines the single source of truth for how this AI agent team understands, develops, and delivers software projects. It mandates a consistent structure and a documentation-first workflow to ensure clarity, reproducibility, and effective collaboration.

Core Principles (All Roles)

1. Documentation is Paramount: Every significant decision, requirement, and procedure must be written down in the prescribed location.
2. Traceability: Code and features must be traceable to a source requirement (docs/01-REQUIREMENT.md) or a recorded decision (docs/02-DESIGN/).
3. Reproducibility: Any team member must be able to build, test, and deploy the project using only the instructions in this repository.
4. Explicit State: The current state of work, bugs, and ideas must be visibly tracked, ideally in a synchronized project management system.

Project Structure & Canonical Documents

Each project shall have a top directory under teamshared/ directory, e.g. teamshared/<project_name>/. Under the top directory, follow below rules to manage project files.

The following directory and file structure is mandatory. All paths are relative to the project root (./).

./ ├── README.md # Project's front page and main index. ├── docs/ # Primary documentation directory. │ ├── 00-ROADMAP.md # Product roadmap: FEAT-xxx (enhancements) & IDEA-xxx (future). │ ├── 01-REQUIREMENT.md # All user requirements: functional (FR), non-functional (NFR), + FEAT/IDEA refs. │ ├── 02-DESIGN/ # Architecture and decision records. │ │ ├── INDEX.md # Index of all Architectural Decision Records (ADRs) + archive index. │ │ └── ADR-001-title.md # Individual ADR (see format below). │ ├── 03-TEST.md # Acceptance criteria, test plan, and results. │ ├── 04-DEPLOY.md # Step-by-step build, deployment, and ops procedures. │ ├── 05-USER_DOCUMENT.md # End-user guide, API reference, or manual. │ ├── 06-DOMAIN_SPECIFIC/ # (Optional) Domain-specific module documentation. │ ├── 07-TEST_RESULTS.md # Latest test results report (counts, coverage, per-fix mapping). │ ├── 08-ARCHIVE/ # Completed milestones, ADR implementation summaries, historical reports. │ │ └── HISTORY.md # Archived completed items (moved from PROJECT_BOARD.md). │ └── references/ # (Optional) Extended reference docs (e.g., architecture diagrams, legacy design notes). ├── src/ # Application source code. ├── tests/ # Automated test suites (layered - see §Test Layering below). │ ├── unit/ # Pure unit tests: single class/function, all deps mocked. │ ├── functional/ # Multi-component wiring: CLI end-to-end, real in-memory DB, mocked boundary. │ ├── acceptance/ # End-to-end with real network/DB/external systems. │ └── pytest.ini # Test config (MUST set --import-mode=importlib for layered tests/). ├── scripts/ # Build, utility, and environment scripts. ├── PROJECT_BOARD.md # Active work tracking (completed items archived to 08-ARCHIVE/HISTORY.md). ├── MONITORING_STATUS.md # (Optional) Data source / system health monitoring status. ├── SUGGESTIONS.md # (Optional) User/team suggestions and feedback log. └── [dependency files] # e.g., requirements.txt, package.json, pyproject.toml.

(*): File may live in a different standard location for the project's language/framework.

Numbering Convention for docs/

Documents under docs/ use a zero-padded NN- prefix to enforce a logical reading order:

1. README.md - The Project Index

Purpose: The first point of entry. It must orient a new developer or user in under 5 minutes. Content Must:

• Project Name & Brief Description: What it is, in one paragraph.
• Current Status: "Active / In Planning / Archived". Link to the main PROJECT_BOARD.md.
• Quick Start: A 3-5 command sequence to get a development environment running.
• Full Document Index: Direct links to every document in the docs/ directory.
• Team & Contact: Point of contact for questions.

2. docs/00-ROADMAP.md - The "Where We're Going"

Purpose: Track product roadmap items that are not yet refined into functional requirements. Content Must:

• Completed Milestones Overview: High-level summary table (details go to 08-ARCHIVE/HISTORY.md).
• FEAT-xxx Items: Planned feature enhancements (e.g., FEAT-001 Parameter Optimization). Include status and estimated effort.
• IDEA-xxx Items: Long-term, unprioritized ideas (e.g., IDEA-001 Multi-data-source support).
• Refinement Rules: When a FEAT is started, refine it into one or more functional requirements (FR) and append them to 01-REQUIREMENT.md with a 参考: FEAT-xxx annotation.

Key Rule: Do not split or refine FEAT/IDEA items in this file. Only refine them when the item is actually being started, and the refined FRs go to 01-REQUIREMENT.md, not back here.

3. docs/01-REQUIREMENT.md - The "Why"

Purpose: Define the problem, stakeholders, goals, and what "done" looks like. This file contains all user requirements. Content Must:

• Problem Statement: The pain point or opportunity this project addresses.
• Goals & Non-Goals: Clear, measurable objectives and explicit exclusions.
• User Personas & Stories: Who uses this and what they need to accomplish.
• Functional Requirements (FR-xxx): Specific capabilities, each with a unique ID. When an FR is refined from a FEAT, annotate with 参考: FEAT-xxx.
• Non-Functional Requirements (NFR): Performance, security, reliability needs.
• FEAT/IDEA Reference Index: A section (e.g., §10) listing all FEAT-xxx and IDEA-xxx IDs with links to 00-ROADMAP.md for details.

Key Rule: FEAT-xxx and IDEA-xxx items themselves do not live here — only their refined FRs (with back-references) and a reference index.

4. docs/02-DESIGN/ - The "How" and "Why This Way"

Purpose: Record the significant architectural and high-level design decisions. Process: Major decisions are recorded as Architectural Decision Records (ADRs).

• File Naming: ADR-001-use-python-fastapi.md
• ADR Lifecycle:
  1. Create the ADR design file in docs/02-DESIGN/ when the decision is made.
  2. When implementation completes, write an implementation summary and archive it to docs/08-ARCHIVE/ (e.g., ADR-007-IMPLEMENTATION-SUMMARY.md).
  3. Add an "实施记录与归档" (Implementation Records & Archive) section at the end of the ADR design file, linking to the archived summary.
  4. Update docs/02-DESIGN/INDEX.md with the ADR entry and an archive index table.

• ADR Format (Template):

  # [ADR-001] Use Python and FastAPI
  
      Status: [Proposed | Accepted | Superseded by ADR-002]
      Deciders: [Architect Agent, Developer Agent]
      Date: 2023-10-27
  
  ## Context and Problem Statement
  
  [The motivating context and the problem we are solving.]
  
  ## Decision Drivers
  
      [Driver 1, e.g., Development speed]
      [Driver 2, e.g., Team familiarity]
  
  ## Considered Options
  
      [Option 1]
      [Option 2]
      [Option 3, including the chosen one]
  
  ## Decision Outcome
  
  Chosen option: "[Option 3]", because...
  
  ## Consequences
  
      Positive: [e.g., Rapid prototyping, strong async support.]
      Negative: [e.g., Python's runtime performance trade-off.]
  
  ## Implementation Records & Archive
  
  > Implementation summaries are archived in [../08-ARCHIVE/](../08-ARCHIVE/).
  
  | Document | Description | Status |
  |----------|-------------|--------|
  | [ADR-001-IMPLEMENTATION-SUMMARY.md](../08-ARCHIVE/ADR-001-IMPLEMENTATION-SUMMARY.md) | Implementation completion summary | ✅ Completed (YYYY-MM-DD) |

5. docs/03-TEST.md - The "Verification"

Purpose: Define how we verify the system works as required. Content Must:

• Testing Strategy: Unit, functional, acceptance testing approach (see §Test Layering below).
• Acceptance Test Matrix: Links requirements (FR-xxx) to specific test cases/scenarios.
• Results & Status: Current test pass/fail status. Detailed results go in 07-TEST_RESULTS.md.

6. docs/04-DEPLOY.md - The "Delivery"

Purpose: Provide complete, copy-pasteable instructions to go from source to a running system. Content Must: Be a runbook. Assume the person reading it has the repo but no other context.

• Prerequisites: OS, installed tools (Docker, Node, Python) with version numbers.
• Environment Variables: All required ENV vars, with examples or links to vault.
• Step-by-Step Commands: For local dev setup, staging, and production deployment.
• Health Checks: How to verify the deployment was successful.

7. docs/05-USER_DOCUMENT.md - The "User Manual"

Purpose: Teach an end-user how to achieve their goals with the system. Content Must be tailored:

• For Applications: Tutorials, how-to guides, screenshot walkthroughs.
• For Libraries/APIs: Getting started, comprehensive API reference, examples.

8. docs/07-TEST_RESULTS.md - The "Test Report"

Purpose: Provide a living report of the latest test results, separate from the test strategy in 03-TEST.md. Content Must:

• Overview: Total test count, pass/fail counts, test file count.
• Test File Listing: Organized by layer (unit/functional/acceptance) with per-file test counts.
• Bug/Fix Tracking: A table mapping each fixed bug (e.g., Section A/B items) to the specific test class(es) and test count that verify the fix.
• Coverage Gaps: Known untested areas.
• Run Commands: How to run each test layer independently.

9. docs/08-ARCHIVE/ - The "Memory"

Purpose: Consolidate all completed and historical documentation to keep living docs (docs/ root) clean. Content Includes:

• HISTORY.md — Completed milestones and items moved from PROJECT_BOARD.md.
• ADR-xxx-IMPLEMENTATION-SUMMARY.md — ADR implementation summaries (linked from the ADR design file in 02-DESIGN/).
• ADR-xxx-P0-FIXES-SUMMARY.md — Bug fix reports tied to an ADR.
• Historical review/report files (e.g., REVIEW.md, phase1_completion_report.md, P0_FIXES_SUMMARY.md).

Key Rules:

• This directory is append-only: never edit or delete archived content (use new files for corrections if needed).
• Archived ADR summaries must be linked from their parent ADR design file in 02-DESIGN/ via an "实施记录与归档" section.
• When items in PROJECT_BOARD.md are completed, move them to 08-ARCHIVE/HISTORY.md and remove from the board.

10. PROJECT_BOARD.md - The "Living State"

Primary Rule: Do not let this file become stale. It is the heartbeat of the project. It must contain only active/incomplete tasks — completed items are archived to docs/08-ARCHIVE/HISTORY.md. Preferred: Update it whenever you add a new task, or finish a task. It must be strictly maintained in the following sections:

• ## In Progress (Current sprint/cycle work)
• ## Backlog (Prioritized future work)
• ## Blocked (Work waiting on external input)
• ## Ideas & Future (Unprioritized ideas — or reference 00-ROADMAP.md for FEAT/IDEA items)

Completed Items: When a task is done, move its entry to docs/08-ARCHIVE/HISTORY.md (do not leave a stale "Completed" section in the board). Keep only a brief pointer if needed.

FEAT/IDEA Items: Do not maintain FEAT-xxx / IDEA-xxx tables in PROJECT_BOARD.md — they live in docs/00-ROADMAP.md. The board may contain a one-line pointer to the roadmap.

Test Layering (tests/)

Tests are organized into three layers by scope and dependency isolation. Each layer has a distinct purpose and run profile.

Rules

1. Pure unit tests test a single class/function with all dependencies (DB, network, filesystem) mocked or stubbed. They must be deterministic and never touch the network.
2. Functional tests exercise multiple real components together (e.g., CLI via CliRunner → Service → DAO with in-memory SQLite). Mock only at the system boundary (external APIs, real network).
3. Acceptance tests verify real user journeys end-to-end, including real external systems (HTTP APIs, real DB). They may be flaky and should be run manually or nightly, not on every commit.
4. Mixed test files (containing both unit and functional tests) must be split into separate files in the appropriate subdirectory. Use the same basename across directories if needed.
5. pytest.ini must set addopts = --import-mode=importlib to allow same-basename test files across unit/, functional/, and acceptance/ subdirectories without __init__.py conflicts.
6. Test file naming should reflect the functionality/scenario being tested (e.g., test_holdings_backtest_data_validation.py), not the development phase.

Running Tests by Layer

# Unit only (fast, deterministic, no network)
pytest tests/unit/

# Functional (real DB, CLI end-to-end, no network)
pytest tests/functional/

# Acceptance (real network — run manually/pre-release)
pytest tests/acceptance/

# All
pytest tests/

How to Use This Skill: Agent Workflows

When starting work or reviewing a project:

1. Always begin by reading the README.md.
2. Understand the "Where we're going" by reviewing docs/00-ROADMAP.md (FEAT/IDEA items, milestones).
3. Understand the "Why" by reviewing docs/01-REQUIREMENT.md.
4. Understand the "How" by reviewing the latest ADRs in docs/02-DESIGN/.
5. Check the current state in PROJECT_BOARD.md.
6. For historical context, review docs/08-ARCHIVE/HISTORY.md.

When implementing a new feature or fix:

Depend on your role, check your corresponding rules:

• PJM: pjm.md
• Architect: architect.md
• Developer: developer.md

Always update PROJECT_BOARD.md when work items are created or status are changed. When a task is completed, move it to docs/08-ARCHIVE/HISTORY.md.

When writing or organizing tests:

1. Place tests in the correct layer: tests/unit/, tests/functional/, or tests/acceptance/ (see §Test Layering above).
2. Split mixed test files by type — never mix unit and functional tests in the same file.
3. Ensure pytest.ini has --import-mode=importlib enabled.
4. After test changes, update docs/07-TEST_RESULTS.md with new counts and per-fix coverage mapping.

When stuck or planning:

1. Review relevant ADRs in docs/02-DESIGN/ for context (check the "实施记录与归档" section for archived summaries).
2. Log the blocker in PROJECT_BOARD.md under "Blocked", or log the idea in docs/00-ROADMAP.md under FEAT/IDEA items.
3. For completed work context, consult docs/08-ARCHIVE/HISTORY.md.