Project Guidelines

Purpose: Explain, for a human, what "project guidelines" are, why they matter, and the small set of files you can actually edit to shape how Swifter generates code. This page is the overview and the decision map; the full per-area file inventories live in the three reference pages it links to.

Reading time: ~6 minutes · Audience: tech lead / architect (FDE pairs on first pass).

Why guidelines are inputs, not documentation

In Swifter, project guidelines are stored under .swifter/specs/{module}/overview/ and provide the AI agents with everything they need to write code that follows the project's established patterns.

The more thoroughly the project's patterns, architectural approaches, and project-specific requirements are documented, the closer Swifter's output will be to the expected result. Properly configuring project guidelines reduces the need for additional code refinements and iterative "vibe coding," ultimately improving both development speed and code quality.

For example, frontend Overview (specs/frontend/overview/) is a high-level project knowledge:

File	Purpose
ARCHITECTURE.md	Application architecture and module organization
CONVENTIONS.md	Coding standards, styling rules, naming conventions
STACK.md	Technology stack details (Angular, Tailwind, etc.)
STRUCTURE.md	File/folder structure conventions
TEMPLATES.md	Code templates and patterns
TESTING.md	Testing approach and conventions
INTEGRATIONS.md	External integrations
CONCERNS.md	Cross-cutting concerns
framework_knowledge.md	Framework-specific patterns and APIs
storybook_knowledge.md	Storybook setup and usage

framework_knowledge.md serves as an index/entry point for framework knowledge. It contains:

• External links — research sources pointing to official Angular documentation (Signals, Components, DI, Forms, SSR, Testing, Material Theming, etc.)
• Internal references — a table mapping each overview file to its content area (STACK.md, STRUCTURE.md, ARCHITECTURE.md, etc.)
• Quick reference — build/test/dev commands
• Metadata — framework version, generation date, package.json location

So, agents use framework_knowledge.md as a starting point to navigate to the right detailed file or external doc depending on what they need.

IMPORTANT! If Swifter generates code that does not meet expectations, avoid fixing the code as the first step. Instead, use the chat to update the framework knowledge with rules that would prevent the same issue from occurring in the future.

After updating the rules, ask Swifter to review the generated code for compliance with the framework knowledge and apply any necessary corrections. This approach not only resolves the current issue but also helps prevent similar mistakes in subsequent tasks.

With each refinement of the framework knowledge, Swifter becomes more closely aligned with the project's requirements, patterns, and conventions. Over time, this leads to faster task completion, higher-quality output, and fewer clarifications or manual adjustments.

What you can actually shape — the levers

Most of overview/ is generated for you. You shape agent behaviour through a small set of levers. This is the whole game; the reference pages just expand each one.

1. The core overview/ files — hand-edit between runs

Eight files carry the bulk of the rules an agent obeys: STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS, PITFALLS. Both backend and frontend modules have files by these names (they're produced by different generators — see the reference pages).

How: hand-edit the file directly. The change takes effect on the next agent generation immediately. New anti-pattern the reviewer keeps flagging → add a row to PITFALLS.md. Naming-convention change → amend CONVENTIONS.md.

Caveat: on a backend module, the next architect amendment round re-scans these files and may rewrite them — so hand-edits are best for incremental between-run tweaks; durable structural changes go through the gate (lever 3). → Backend reference · Frontend reference

2. Frontend: drop a project style guide (the cleanest FE lever)

The frontend knowledge files are auto-generated by the refresh-framework-knowledge skill, so hand-edits get regenerated away. The durable lever is that the skill scans project markdown (.swifter/specs/{module}/overview/*.md excluding generated files, and **/*.md across the project) as research input — and project conventions override framework defaults when a style guide is present.

How: put a markdown style guide at the project root (e.g. STYLE_GUIDE.md), with headings that mirror the knowledge files (CONVENTIONS, STRUCTURE, …). The skill ingests it on the next refresh and folds your rules into the generated CONVENTIONS.md / STRUCTURE.md / etc. → Frontend reference

3. Backend: the architect's 6-topic gate

On a backend module, the most direct shaping happens during swifter-backend-architect:create-guidelines, which drives a blocking 6-topic confirmation gate: architecture approach, codebase locations, suggestions, pitfall mitigations, NFR scope, mandatory principles. This is also the only good way to change the NFR files and CODING_GUIDELINES.md — those are gate-shaped / derived and ignore hand-edits.

How: answer the gate thoughtfully on the first run; re-run the architect (an "amendment round") to revise. → Backend reference

4. The tester knowledgebase

A project-level .swifter/knowledgebase/ folder of free-form markdown holds client-specific testing guidance (selectors, auth, navigation). Only the swifter-tester agent reads it.

How: create any markdown file under .swifter/knowledgebase/; the tester reads every file on each test-generation run, no schema required. → Tester reference

Lever summary

Lever	What it shapes	How
Core overview/ files	Most generation rules (BE + FE)	Hand-edit; effective next run
FE project style guide	Auto-generated FE knowledge files	Drop a STYLE_GUIDE.md at project root; ingested on refresh
Architect 6-topic gate	BE architecture, NFR scope, coding rules	Answer the gate; re-run to amend
Tester knowledgebase	Test selectors / auth / navigation	Add markdown under .swifter/knowledgebase/

Principles for what to write inside the files

Whatever the file or lever, what you write inside follows these principles. They are meta-rules about content shape — not specific rules like "ban RxJS" — so the same eleven apply to FE, BE, and test guidelines.

1. Pin the stack. Name framework, libraries, and tool versions explicitly. Without versions, generated code drifts to "popular but wrong-version" idioms.
2. State forbidden technologies. List what agents must NOT reach for. Without explicit bans, generated code reintroduces forbidden tech every time.
3. Pair every ban with an allowed alternative. A ban without an alternative leaves the agent stuck. Always state what to use instead.
4. Define boundary exceptions narrowly. Where a framework boundary forces the forbidden tool, declare a narrow allowlist with the exact pattern. The agent needs both the rule and the escape valve.
5. Lock one canonical pattern per concern. Pick ONE pattern for each concern (state management, dialog opening, HTTP, error handling, async). Two equally good patterns are worse than one — the agent alternates between them.
6. Separate UI from orchestration. Dumb components emit events and own no state; services own state and decisions. Name the separation and show the wrong shape so the agent recognises it.
7. Prefer the project's component library. Name the wrappers agents must reuse before reaching for primitives. Maintain a discoverable index of library components.
8. Name the file structure. Declare directory layout, page-vs-component conventions, where everything lives. Capture it as an ASCII tree near the top.
9. Encode anti-patterns. List the failure modes you've observed (empty placeholder files, metadata comments in generated source, hardcoded test values, raw as any casts). Every "the agent did the wrong thing again" is an anti-pattern that belongs in the guidelines.
10. Encode behavioural commands. Name the exact build / test / lint / format commands the agent should run, so generated code passes your gates.
11. Show before / after examples. Pair every rule with a wrong-vs-right snippet. Agents follow patterns far better than abstract directives.

First-run / generation order

For a brand-new project:

1. Backend module(s) — run swifter-backend-architect:create-guidelines first. Review STACK.md, ARCHITECTURE.md, CONVENTIONS.md, PITFALLS.md first; NFRs second when explicit non-functional requirements exist.
2. Frontend module(s) — refresh-framework-knowledge and refresh-storybook-knowledge populate the FE overview files on the first analyst run (and ingest any project style guide).
3. Testing module — the same architect scan applies; TESTING.md carries Playwright patterns, allowed selectors, banned timing idioms.

Generate the backend module's guidelines before opening any backend implementation Work Item. (Observed on this team's projects: implementation Work Items did not reach DONE until the overview/ set existed, then the completion rate climbed — an empirical observation, not a hard platform gate.)

Guidelines are never "done." Every PR that surfaces an anti-pattern is a candidate for a new PITFALLS.md / CONVENTIONS.md entry. Treat overview/ as a living document the team owns, and rerun the refresh skills whenever a dependency version changes.

Reference pages

• Backend guidelines — the 16-file set the backend architect produces, the uniform line budget, the 6-topic gate, the regeneration model, and the per-agent reader matrix.
• Frontend guidelines — the 9-file split from refresh-framework-knowledge, the framework_knowledge.md entry point, Storybook knowledge, the STOP prerequisites, and the project-style-guide ingestion mechanism in detail.
• Tester guidelines — the .swifter/knowledgebase/ surface, what the tester reads, the selector-priority strategy, and where guidance is applied.