patterns: manage the cross-project pattern library

paqad-ai patterns lets you look after the pattern library: a store of past problems and the solutions that worked, kept on your machine and shared across all your projects. A pattern records what the problem was, how it was solved, which stack it applies to, and whether tests and the build passed afterwards.

The command has three subcommands: list, prune and export. It does not create patterns.

Where the library lives

The library is stored in your home folder at ~/.paqad/patterns/: one JSON file per pattern under entries/, plus an index.json. Because it sits outside any project, every project on the machine sees the same library, and it is not committed to any repository.

How patterns are used

• During planning, Paqad's solution-architect instructions tell the AI to check ~/.paqad/patterns/ for similar problems from other projects before it designs an approach. Whether a pattern is relevant is the AI's judgment.
• Adding patterns happens through Paqad's programmatic interface (the PatternRecorder in the paqad-ai package). There is no patterns add command in this release.

How patterns are ranked for suggestions is covered below and on pattern scoring.

List patterns

paqad-ai patterns list [--domain <domain>] [--category <category>] [--frameworks <a,b>] [--keywords <a,b>]

Prints each pattern's short ID, category, the start of the problem text, its frameworks, tags and creation date. The filters narrow the list:

• --domain: exact match on the pattern's domain, such as coding.
• --category: exact match on the category.
• --frameworks: comma-separated; keeps patterns that list any of these frameworks, for example --frameworks laravel,vue.
• --keywords: comma-separated; keeps patterns whose problem preview (its first 100 characters) or tags contain any of the words.

paqad-ai patterns list --frameworks laravel --keywords auth,login

Prune old patterns

paqad-ai patterns prune [--older-than <days>]

Deletes patterns created more than the given number of days ago. The default is 180. Pruning works on age only, and the files are removed from disk, so export first if you want a copy.

Export the library

paqad-ai patterns export <output> [--format json|markdown]

Writes every pattern to the file you name. JSON (the default) keeps all fields and suits sharing with a teammate or another machine. Markdown produces a readable document with each pattern's problem and solution.

paqad-ai patterns export patterns.json
paqad-ai patterns export patterns.md --format markdown

How suggestions are scored

The paqad-ai package also contains a pattern suggester for integrations to call; no CLI command runs it in this release. It first keeps patterns from the same domain that share at least one framework with the task, then adds up three parts, each between zero and its maximum weight:

Part	Weight	What it measures
Framework match	0.25	Share of the task's frameworks that the pattern lists.
Keyword match	0.35	Share of the task's keywords found in the pattern's problem text or tags.
Meaning match	0.40	Similarity from the RAG search index, when one is available. Without it, this part is zero.

Patterns older than 180 days lose 0.15. Only patterns scoring at least 0.3 are suggested, and at most three are returned. These scores are calculated by a script; choosing whether to follow a suggestion stays with the AI and the person reviewing its work.