Customization & Best Practices

This guide outlines how to evolve the Spec Kit integration as NexisChat grows—tuning prompts, automating validation, scaling artifact management, and enabling multi-agent collaboration.

Guiding Principles

Principle	Why It Matters
Intent Before Implementation	Prevent scope creep & misaligned architecture
Deterministic Artifacts	Easier diff/review; lowers ambiguity for AI
Minimal Stable Surface	Only bake durable policies into constitution/prompts
Regenerate Intentionally	Avoid drift by upstreaming changes rather than ad-hoc patches
Small, Observable Increments	Faster feedback loops & reduced merge conflict risk

Prompt Tuning Strategy

Goal	Technique	Example
Increase structural consistency	Add numbered required sections	”Return sections 1–8 exactly; omit others”
Reduce hallucinated scope	Add explicit negative constraints	”Do NOT introduce authentication primitives unless spec defines them”
Encourage alternatives	Ask for variants with trade-offs	”Provide 2 plan options: baseline vs. queue-backed”
Improve edge case coverage	Require explicit table	”Add an Edge Cases table with Trigger / Expected Behavior”

Keep prompts under size thresholds to avoid truncation; move large constant policies into constitution.

Constitution Management

Add a Changelog section at bottom of memory/constitution.md:

### Change Log
- 2025-09-10: Added rule enforcing feature flags for experimental UI flows.

Perform monthly review (or sooner if major architecture shifts). Remove obsolete guidance to reduce noise.

Artifact Lifecycle

Stage	Action	Ownership
Draft	Generated by AI, refined via review	Feature Owner
Approved	Stored & versioned in repo	Maintainer / Reviewer
Amended	Upstream change triggers regeneration	Maintainer + Owner
Archived	Deprecated feature or replaced design	Architecture Lead

Consider prefixing archived artifacts with archive__ or relocate to /archive/.

Scaling Tasks

When task lists exceed ~100 items:

• Group by workstream (e.g., API, UI, Infra, Migrations)
• Maintain a master index referencing sub-task files
• Add progress markers (e.g., [37/112 complete] auto-updated via script)

Automation Ideas

Automation	Value
Lint: required spec sections	Stops incomplete artifacts early
Plan diff tool	Compare alternative architectures programmatically
Task size heuristic	Warn if task may exceed LOC threshold
Constitution hash check	Warn if changed without checklist update
Edge case enumerator	Script to scan for “Edge Cases” heading presence

Recommended Make Targets

make feature slug=team-workspaces        # scaffold spec/plan/tasks
make plan slug=team-workspaces           # run setup-plan + open plan file
make tasks slug=team-workspaces          # generate tasks after plan approval
make validate-artifacts                  # run custom lint checks

Multi-Agent & Parallelism

If multiple AI agents (e.g., Copilot + Claude) are used:

• Standardize artifact contract so outputs are interchangeable.
• Use a /_agent/ metadata block in artifacts capturing: model, temperature, date.
• Diff alternative implementations before selecting (store losing variants briefly for rationale capture).

Testing Alignment

Embed references to test strategy per task:

- [ ] Add unit tests (services)
- [ ] Add integration tests (API endpoints)
- [ ] Add contract tests (schema payload variants)

Automate validation: fail CI if new feature merges without at least one test file touched unless explicitly exempted (label: test-exempt).

Observability Integration

During /plan phase require explicit:

• Metrics (counters, histograms)
• Logs (structured keys)
• Traces (critical spans)

Reject plans missing an Observability section unless intentionally trivial.

Security & Compliance Hooks

Add to prompts once stable:

• Data classification tags per data model
• Threat model sketch (STRIDE table)
• Access control matrix (Role x Action)

Refactoring & Modernization

For legacy modules:

1. Capture existing behavior spec first (reverse spec)
2. Propose modernization plan (parallel variant acceptable)
3. Generate tasks for strangler pattern migration

Metrics to Track

Metric	Definition	Why
Spec Iteration Count	Number of revisions pre-approval	Detect over-churn or under-review
Avg Task Cycle Time	Start → merged	Flow efficiency
Regeneration Frequency	Spec/plan rework per feature	Architectural stability signal
Task Size Distribution	LOC per task diff	Scope health

Smarter Context Engineering (Future)

• Generate dependency graphs & embed summaries in plan context.
• Summarize frequently imported modules (size/touch frequency).
• Auto-extract data models and feed into /plan.

Adoption Playbook

Phase	Goal	Indicator
Pilot	Validate workflow value	Reduced rework comments in PRs
Expansion	Onboard more contributors	Increased spec artifacts per sprint
Maturity	Normalize regeneration discipline	Stable regeneration frequency

Pitfalls & Mitigations

Pitfall	Mitigation
Over-specifying trivial features	Apply lightweight template variant
Stale constitution entries	Quarterly pruning session
Ignoring open questions	Block plan approval until answered or deferred explicitly
Task avalanche (too granular)	Minimum size heuristic / merge tasks

Quick Checklist (Feature Kickoff)

[ ] /specify complete & reviewed
[ ] /plan approved (constraints aligned)
[ ] /tasks granular & validated
[ ] Observability & security sections present
[ ] Constitution still applicable (no contradictions)
[ ] Automation lint passes

Enhance this doc as we implement automation or adopt new AI workflows.