sechmachine/labtimesheet
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive implementation and design guidelines

Browse Source
This commit is contained in:
sechmachine
2026-08-15 13:04:50 +07:00
parent bca30e6e4b
commit 8be1b754e1
8 changed files with 1094 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/orchestrate-labtimesheet-iteration/SKILL.md
+210
View File
@@ -0,0 +1,210 @@
---
name: orchestrate-labtimesheet-iteration
description: Use when initiating, resuming, integrating, or completing a multi-branch Lab Timesheet iteration defined by .agents/PROJECT_PLAN.md.
---
# Orchestrate a Lab Timesheet Iteration
Run the iteration continuously from repository audit through an evidence-backed local exit demonstration. Preserve the five long-lived work branches and keep business features isolated behind public services and DTOs.
## Load authority and preserve state
1. Read the repository `AGENTS.md`, `.agents/PROJECT_PLAN.md`, `PRODUCT.md`, `DEVELOPMENT.md`, `TESTING.md`, and the applicable numbered requirements in `labtimesheet-docs-hub/requirements-specification.md`.
2. Apply authority in this order: current user decisions, numbered requirements, approved plan, tests/code, then inference.
3. Inspect every worktree and the root `git status` before mutation. Record and preserve unrelated dirty or untracked files.
4. Confirm the actual Maven, Spring Boot, Java, Node, PostgreSQL, Flyway, and Testcontainers versions. Use the documented project baseline even if a newer JDK is installed.
5. Create or update the active goal and plan only when the user requests goal-mode execution.
## Enforce the project structure
Keep `LabtimesheetApplication` in `com.lab.labtimesheet`, shared wiring in `config`, and business code under:
```text
feature.account
feature.integration
feature.project
feature.task
feature.attendance
feature.notification
feature.reporting
```
Repeat only the layers a feature needs: `controller`, `model`, `model.dto`, `model.entity`, `repository`, `service`, and `exception`. Mirror these packages in tests.
- Call another feature only through its concrete public service methods and DTOs.
- Never import another feature's repository or JPA entity.
- Use Spring Data JPA for business persistence.
- Limit direct SQL to Flyway and schema/catalog verification.
- Do not add empty `common`, `core`, `utils`, or boundary-placeholder packages.
- Do not add one-implementation interfaces, shadow mappings of foreign tables, or speculative abstractions.
Use the installed Lombok processor as the default for safe Java boilerplate:
- `@RequiredArgsConstructor` for injection-only constructors with required final dependencies;
- targeted `@Getter`, `@Setter`, and protected `@NoArgsConstructor` instead of blanket `@Data`;
- no generated JPA entity `equals`, `hashCode`, or `toString` over mutable state, associations, or secrets;
- records remain records for immutable DTOs and commands;
- explicit constructors and methods remain when they validate, normalize, enforce invariants, preserve history, define identity, or select qualified dependencies.
Require each owner to audit its production package, record a source-contract RED for eligible handwritten boilerplate, make the smallest behavior-preserving Lombok conversion, and prove compile/Javadoc, Spring injection, JPA mapping, template property access, and affected behavior remain green. Do not add annotations that generate unused API.
## Establish the shared baseline first
Before dispatching feature work:
1. Verify the Maven wrapper, application profile, Flyway baseline, PostgreSQL connectivity, test-only clock/encryption, and frontend asset toolchain.
2. Run a clean baseline test and capture any pre-existing failure separately.
3. Run the application locally against a disposable or dedicated PostgreSQL service. A PostgreSQL or Mailpit test container is acceptable; do not containerize the application when the exit gate says local process.
4. Commit the shared platform foundation before dependent branches use it.
5. Hand off only full immutable commit SHAs from clean worktrees.
## Own five branches and worktrees
Use exactly these persistent branches unless the user changes the plan:
| Branch | Ownership |
|---|---|
| `work/platform` | Baseline, migration, accounts, security, bootstrap, integrations, notification plumbing |
| `work/projects` | Projects, membership, leadership, lifecycle, project authorization |
| `work/tasks` | Tasks, comments, work logs, status, task progress |
| `work/attendance` | Policy, calendar, attendance, corrections, leave, metrics |
| `work/reports-ui` | Shared Thymeleaf UI, dashboards, reports, exports |
Create one isolated worktree per branch. Give each implementation agent explicit ownership, tell it other agents share the repository, forbid reverting others' work, require medium-milestone local commits, and forbid push unless separately authorized.
Before any owner edits its module, require it to:
1. verify its worktree has no uncommitted changes;
2. confirm the taskmaster's exact latest `main` SHA;
3. fast-forward its persistent work branch to that SHA with `git merge --ff-only main`;
4. prove `git rev-parse HEAD` equals the supplied main SHA;
5. stop rather than resolving unexpected divergence or overwriting user work.
Store durable coordination under `.superpowers/sdd/PROJECT_PLAN/`:
- `progress.md` with exact SHAs, dependency pins, tests, blockers, and review rounds;
- one task report per branch;
- review packages and reviewer reports.
Trust this ledger and Git history after context compaction. Never redispatch a completed milestone.
## Require RED, GREEN, Javadoc, and companion evidence
For every behavior:
1. Read its requirement and acceptance scenario IDs.
2. Write the narrowest production-shaped test first.
3. Run it and record RED for the expected missing behavior, not an environment or test defect.
4. Implement the minimum coherent change and its meaningful Javadoc in the same milestone. Document every new or materially changed production type and declared public/protected method, emphasizing business contracts, authorization, transactions/locking, state/history semantics, units, and time boundaries rather than restating names.
5. Run focused GREEN, affected-suite verification, then the branch-wide suite.
6. Refactor only while tests remain green.
7. Commit when a medium milestone is complete.
Use PostgreSQL 18.4 Testcontainers for persistence semantics; do not substitute H2. Keep time and randomness controllable. Test public outcomes, persisted state, authorization denial, and boundary cases.
Create a Markdown evidence record under the matching directory:
```text
docs/tests/unit/
docs/tests/integration/
docs/tests/web/
docs/tests/e2e/
```
Start from that directory's `_TEMPLATE.md`. Every record must include requirement/scenario IDs, protected behavior, test method, hand-derived expected result, exact RED command/result, exact GREEN and affected-suite commands/results, implementation milestone, and external-test boundaries. Never replace executable evidence with a verbal claim.
Iteration 1 is the only retrofit exception: after all feature tasks finish, return each branch to its original owner to add missing Javadocs before integration, rerun affected verification, commit, and undergo scoped re-review. In every later iteration or turn, reject delayed Javadoc cleanup; it belongs in the implementation milestone.
## Merge dependencies by immutable pin
Derive the dependency graph from the current iteration plan. For Iteration 1, use:
```text
platform foundation
-> projects base
-> attendance
-> tasks (projects + attendance public APIs)
-> projects activation guard (final Task query API)
-> reports-ui (final public dashboard APIs)
```
- A producer reports a clean full SHA and public API before a consumer merges it.
- Never merge a moving branch or a short ambiguous SHA.
- Preserve dirty consumer work during the merge and immediately rerun its structure test.
- If a consumer needs data, add the smallest producer-owned public query DTO/service method; never map or query the producer's tables locally.
- Keep final integration order from `.agents/PROJECT_PLAN.md` even when development dependencies require a temporary producer/base round trip.
- Reuse the last reviewed consumer branch as the integrated candidate when it already contains every approved producer pin in order. An extra integration branch adds no safety by itself.
- After a Platform merge, run the architecture test and every `@WebMvcTest` controller slice. Global advice and shared beans can invalidate otherwise unrelated slice fixtures; fix only the test fixture, never production security to accommodate a slice.
## Coordinate agents without losing control
Let the five owners work in parallel where dependencies permit. Resolve normal in-scope questions without pausing the run. Stop only for a genuine blocker, consequential ambiguity, destructive action, or sensitive external effect requiring user approval.
For a sensitive action, state the exact effect and obtain approval in the root task. If a child cannot inherit that approval, the root may apply only the isolated approved patch; return the worktree to its owner for tests, evidence, self-review, and commit.
Do not accept an agent's completion claim alone. Require:
- exact branch and full SHA;
- clean worktree;
- focused, affected, and full test counts;
- confirmation that new/changed production APIs carry accurate Javadoc;
- a list of Lombok conversions and explicit boilerplate deliberately retained with its business reason;
- evidence/report path;
- public API handoff;
- blockers and unverified boundaries;
- confirmation of no push.
## Review only after all five owners finish
After every implementation owner reports `DONE`, dispatch independent code-review assignments, one branch per assignment. Give each reviewer the plan/requirements paths, branch report, ledger, merge base, full diff package, and exact structure/TDD constraints.
Each review must return both spec-compliance and code-quality verdicts with file/line evidence. For Critical or Important findings:
1. Send the complete finding list back to that branch's original owner.
2. Require a focused regression test, RED when applicable, GREEN, affected suite, evidence update, and a fix commit.
3. Dispatch an independent scoped re-review of only the fix range.
4. Repeat up to five rounds; use a fresh stronger fixer for rounds four and five.
5. At the cap, record a reasoned ruling for non-load-bearing findings or stop on a load-bearing blocker.
Do not merge a branch with unresolved load-bearing findings.
## Prove the iteration exit gate
Integrate only reviewed immutable branch SHAs in the plan's order. Then verify from the integrated tree:
1. `git diff --check` and package/JPA architecture tests.
2. Flyway replay against fresh PostgreSQL and the required table/foreign-key catalogue checks.
3. Full Maven tests on the documented Java version and PostgreSQL engine.
4. Frontend asset build on the pinned Node version.
5. A local application process connected to the configured PostgreSQL service.
6. Health/readiness and the iteration's real role-correct web workflow.
7. No application containerization when explicitly deferred.
8. Root dirty-state preservation, clean reviewed worktrees, and no unauthorized push.
Keep environment authority explicit:
- real `.env` files are local and ignored;
- `.env.example` contains placeholders only;
- the development Spring profile maps every required runtime value from the environment;
- Admin-console SMTP and HolidayAPI secrets never move into `.env`;
- configuration-only work uses a shell/configuration RED and real application smoke test instead of an artificial Java unit test.
If SMTP participates in health, exercise both states deliberately: application startup with SMTP deferred, and aggregate health with a real temporary Mailpit connection. Report the distinction instead of calling one state universally healthy.
Store cross-module browser journeys in `docs/tests/e2e/`. Before completion, update every Iteration row and the durable progress ledger; stale `IN_PROGRESS` rows are an incomplete gate even when tests pass.
Review source Javadocs against behavior as part of the branch and integration diff; stale or content-free Javadoc does not satisfy the gate.
## Merge reviewed Iteration work to main
Only enter this phase with explicit user authority.
1. Add any final environment example, profile configuration, implementation-status README, development guide, and testing/TDD guide to the integrated candidate under RED/GREEN evidence.
2. Run the complete PostgreSQL suite and a real local-process smoke test on that exact candidate.
3. Fetch the remote base. Stop on unexpected divergence; never force-push to hide it.
4. Preserve unrelated dirty root files. Commit only separately authorized tracked root guidance before merging if the incoming branch also changes that file.
5. Merge the exact candidate into `main` without squashing or rewriting the reviewed branch history.
6. Rerun the full suite on merged `main`, inspect the diff, and verify `.env` is ignored and absent from the index.
7. Push `main` normally, verify the remote ref equals local `HEAD`, and keep host-managed worktrees unless cleanup was explicitly requested.
Record the integration SHA, commands, outputs, limitations, and deferred next-iteration scope. Mark the goal complete only after every stated exit condition has fresh evidence.