Skip to content

Project Template & Artifact Starter Pack

This page consolidates the starter structural patterns your team should adapt (not copy blindly). These complement the Planning Labs and reduce wheel‑reinvention.

All examples are intentionally concise. Expand with context relevant to your domain.

1. Repository Structure (Suggested Skeleton)

/README.md
/LICENSE
/docs/
  /adr/               # Architecture Decision Records
  /design/            # (Optional) diagrams, sequence charts
/src/                 # Application source
/tests/               # Automated tests
/.github/
  /ISSUE_TEMPLATE/
    bug_report.md
    feature_request.md
  /PULL_REQUEST_TEMPLATE/
    feature.md
    patch.md
    docs.md
    refactor.md
    test.md
  workflows/
    ci.yml            # Lint + test + (build) pipeline
/scripts/             # Utility automation (DB reset, seed, etc.)
Keep top-level clutter low. If adding new root folders, justify their purpose in the README.

2. README Minimal Contract

A strong README accelerates onboarding and TA evaluation.

Section Purpose
Project Pitch One sentence value proposition
Tech Stack Languages, frameworks, notable libs
Quick Start Copy/paste commands to run locally
Test Instructions How to execute all tests (and watch mode if any)
Architecture Snapshot 1–2 paragraph high-level or diagram link
Roadmap Link Point to planning / iteration goals
Contributing PR / issue guidelines summary
License Usage rights clarity

3. Issue Template (Feature Request Example)

## Feature: <short title>
### Problem / Context
(What user problem or gap are we addressing?)

### Proposed Outcome
(User-visible result, not the implementation.)

### Acceptance Criteria (Given‑When‑Then)
- Given ... when ... then ...
- Given ... when ... then ...

### Non-Goals (If Any)
- Explicitly list exclusions.

### Notes / References
(Design links, ADR number, screenshots.)

4. Bug Report Template

## Bug: <short title>
### Environment
(Commit, branch, OS/browser, data state.)

### Steps to Reproduce
1. ...
2. ...

### Expected
What *should* happen.

### Actual
What *did* happen.

### Logs / Screenshots
(Attach or paste.)

### Severity
(blocker, high, medium, low)

5. Pull Request Templates

See PR Templates page for specialized variants (feature, patch, docs, refactor, tests). Keep them in .github/PULL_REQUEST_TEMPLATE/ so authors can choose with the template= query param.

6. ADR Template (Short Form)

# ADR <number>: <Title>

## Status
Proposed | Accepted | Amended | Superseded by ADR X | Deprecated

## Context
What problem or forces are driving this decision? What constraints?

## Decision
The decision made (present tense). Keep it crisp.

## Consequences
Positive, negative, trade-offs, follow-ups required.

When an ADR becomes stale, update status—don’t silently diverge.

7. Test Strategy Snippet

# Test Strategy (Excerpt)
Levels: Unit (fast), Integration (service boundaries), E2E (critical path).

Gate: All unit + integration tests must pass before merge.
Coverage Goal: (If using) lines >= 70% by Iteration 3, function coverage for core modules.
Tools: pytest / vitest / playwright (choose relevant).

Definition of Done additions:
- Tests added/updated
- CI green
- Acceptance criteria satisfied

8. CI Workflow (Conceptual Outline)

name: CI
on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4  # or setup-python / setup-java etc.
        with:
          node-version: '20'
      - name: Install deps
        run: npm ci
      - name: Lint
        run: npm run lint --if-present
      - name: Test
        run: npm test -- --ci
Adjust to your ecosystem; keep jobs fast (< 5 min early on).

9. Status Report Template (Excerpt)

## Iteration N Status Report
**Iteration Goals (Planned vs Achieved)**
- Goal 1: Planned âś” / âś– (brief status)
- Goal 2: ...

**Completed Work**
- #123 Feature X
- #132 Refactor auth module

**Spillover / Deferred**
- #140 Payment integration (blocked by API key access)

**Risks / Blockers**
- Onboarding delay for new member (ETA week 9)

**Metrics (Optional)**
- PRs merged: 14 | Avg review turnaround: 6h

**Next Iteration Draft Focus**
- User profile editing + accessibility pass

10. Common Early Pitfalls

Pitfall Prevention
Oversized PRs Branch often; target ≤ ~300 lines diff
Missing acceptance criteria Enforce in Definition of Ready
Flaky setup instructions Automate in script / update README immediately
Stale ADRs Review ADR index every retro
Testing cliff (none → many late) Add minimal tests in scaffolding, grow steadily

11. Linking Artifacts Together

  • README links to: Roadmap, ADR index, Test Strategy, Contribution guide
  • Each Issue links to: related ADR (if architectural)
  • Each PR links to: Issue + optionally ADR
  • Status Report links to: iteration goals issue + notable PRs

12. When to Create a New ADR

Scenario ADR?
Choice of primary database Yes
Variable naming debate No
Switching auth provider mid-course Yes
Adding a minor npm utility library No
Adopting event-driven model vs REST calls Yes

13. Lightweight Contribution Guide (Inline Option)

If you defer a full CONTRIBUTING.md, embed a section in README specifying: branch naming, PR expectations, commit style, code style references.

Iterate on this template—its value is in continuous fit to your project, not initial perfection.