|
1 | | -# Hermes Profile Template |
| 1 | +# ContextForge RAG |
2 | 2 |
|
3 | | -Build high quality Hermes Agent profile distributions quickly. |
| 3 | +ContextForge RAG is an installable Hermes Agent profile for principal-level production RAG architecture, AI agent workflow design, evaluation, observability, and implementation-ready technical planning. |
4 | 4 |
|
5 | | -This repository is for people who want to create custom Hermes profiles that are installable, safe to publish, easy to maintain, and friendly to AI coding agents. Use it to create a new profile from a few parameters, validate the result, install it locally, then publish it for others to install with `hermes profile install`. |
| 5 | +Template lineage: built from [codegraphtheory/hermes-profile-template](https://github.com/codegraphtheory/hermes-profile-template). |
6 | 6 |
|
7 | | -## What you can do with it |
| 7 | +## What this profile is good at |
8 | 8 |
|
9 | | -- Create a complete Hermes profile distribution from command-line flags. |
10 | | -- Create a deterministic profile from a reusable YAML params file. |
11 | | -- Install this repository as a Hermes profile that helps you create other profiles interactively. |
12 | | -- Validate a profile before publishing it. |
13 | | -- Publish generated profiles so other users can install them from GitHub. |
| 9 | +- Production RAG architecture: ingestion, chunking, embeddings, hybrid retrieval, reranking, citation packing, and model routing. |
| 10 | +- Agent workflow design: intent classification, tool contracts, idempotency, escalation, bounded loops, and failure handling. |
| 11 | +- Evaluation and observability: golden datasets, retrieval metrics, LLM judge rubrics, traces, cost telemetry, and regression gates. |
| 12 | +- Delivery planning: ADRs, implementation-ready GitHub issues, roadmaps, rollout plans, and rollback criteria. |
14 | 13 |
|
15 | | -## Requirements |
16 | | - |
17 | | -- Hermes Agent installed and available as `hermes`. |
18 | | -- Python 3.10 or newer. |
19 | | -- `pyyaml` for validation and generation: |
| 14 | +## Install |
20 | 15 |
|
21 | 16 | ```bash |
22 | | -python3 -m pip install pyyaml |
23 | | -``` |
24 | | - |
25 | | -## Option 1: Use this as a GitHub template |
26 | | - |
27 | | -Open: |
28 | | - |
29 | | -```text |
30 | | -https://github.com/codegraphtheory/hermes-profile-template |
| 17 | +hermes profile install github.com/codegraphtheory/context-forge-rag --name context-forge-rag --yes |
| 18 | +hermes -p context-forge-rag |
31 | 19 | ``` |
32 | 20 |
|
33 | | -Click `Use this template`, create a new repository, then clone your new repo: |
| 21 | +If you cloned the repository locally: |
34 | 22 |
|
35 | 23 | ```bash |
36 | | -git clone https://github.com/YOUR_ORG/YOUR_PROFILE_REPO.git |
37 | | -cd YOUR_PROFILE_REPO |
| 24 | +git clone https://github.com/codegraphtheory/context-forge-rag.git |
| 25 | +cd context-forge-rag |
38 | 26 | python3 scripts/validate_profile.py . |
| 27 | +hermes profile install . --name context-forge-rag --yes |
| 28 | +hermes -p context-forge-rag |
39 | 29 | ``` |
40 | 30 |
|
41 | | -Edit the profile files, then validate again before publishing. |
42 | | - |
43 | | -## Option 2: Create a profile from command-line flags |
44 | | - |
45 | | -```bash |
46 | | -git clone https://github.com/codegraphtheory/hermes-profile-template.git |
47 | | -cd hermes-profile-template |
48 | | - |
49 | | -python3 scripts/new_profile.py \ |
50 | | - --name security-reviewer \ |
51 | | - --display-name "Security Reviewer" \ |
52 | | - --description "Reviews code and architecture for security risk" \ |
53 | | - --output ../security-reviewer |
54 | | - |
55 | | -cd ../security-reviewer |
56 | | -python3 scripts/validate_profile.py . |
57 | | -``` |
58 | | - |
59 | | -Install it locally: |
60 | | - |
61 | | -```bash |
62 | | -hermes profile install . --alias |
63 | | -security-reviewer chat |
64 | | -``` |
65 | | - |
66 | | -## Option 3: Create a profile from a params file |
67 | | - |
68 | | -Copy the sample params file: |
69 | | - |
70 | | -```bash |
71 | | -git clone https://github.com/codegraphtheory/hermes-profile-template.git |
72 | | -cd hermes-profile-template |
73 | | -cp templates/profile.params.yaml /tmp/my-profile.params.yaml |
74 | | -``` |
75 | | - |
76 | | -Edit `/tmp/my-profile.params.yaml`, then generate: |
| 31 | +## Useful first prompts |
77 | 32 |
|
78 | | -```bash |
79 | | -python3 scripts/generate_profile.py \ |
80 | | - --params /tmp/my-profile.params.yaml \ |
81 | | - --output ../my-profile |
82 | | - |
83 | | -cd ../my-profile |
84 | | -python3 scripts/validate_profile.py . |
| 33 | +```text |
| 34 | +Design a production RAG architecture for customer support knowledge retrieval. Include ingestion, metadata, evals, observability, and rollout gates. |
85 | 35 | ``` |
86 | 36 |
|
87 | | -This is the best path when you want reproducible profile creation. The params file becomes the source of truth for the starter profile. |
88 | | - |
89 | | -Generated profiles can include explicit template lineage through the `template_source` field in the params file. GitHub only shows native `generated from` or `forked from` linkage when a repository is created through those GitHub flows, so this template records lineage in `distribution.yaml`, `.github/template-source.yml`, and the generated README. |
90 | | - |
91 | | -## Option 4: Install this repo as an interactive profile builder |
92 | | - |
93 | | -Install the template itself as a Hermes profile: |
94 | | - |
95 | | -```bash |
96 | | -hermes profile install github.com/codegraphtheory/hermes-profile-template \ |
97 | | - --name profile-architect \ |
98 | | - --alias |
99 | | - |
100 | | -profile-architect chat |
| 37 | +```text |
| 38 | +Turn this ambiguous AI feature into 6 implementation-ready GitHub issues with acceptance criteria and eval requirements. |
101 | 39 | ``` |
102 | 40 |
|
103 | | -Then ask it to create a profile: |
104 | | - |
105 | 41 | ```text |
106 | | -Create a Hermes profile for a database migration reviewer. It should inspect SQL diffs, flag destructive migrations, and generate rollback checklists. |
| 42 | +Review my chunking and namespace strategy. Identify failure modes, metrics, and a safe migration plan. |
107 | 43 | ``` |
108 | 44 |
|
109 | | -The installed profile will use the included generator, write a starter profile, and run validation. |
110 | | - |
111 | | -## Validate before publishing |
112 | | - |
113 | | -Run this from the profile repository root: |
| 45 | +## Bundled skills |
114 | 46 |
|
115 | | -```bash |
116 | | -python3 scripts/validate_profile.py . |
117 | | -``` |
| 47 | +- `principal-ai-architect`: ADRs, architecture tradeoffs, diagrams, and decision records. |
| 48 | +- `technical-roadmapping`: delivery sequencing, milestones, dependency mapping, and risk gates. |
| 49 | +- `production-rag-architecture`: retrieval system design, namespace strategy, chunking, embeddings, reranking, and rollout. |
| 50 | +- `rag-evaluation-observability`: golden datasets, metric design, LLM judge rubrics, traces, and regression gates. |
| 51 | +- `agentic-workflow-issue-factory`: implementation-ready issues and typed agent tool design. |
118 | 52 |
|
119 | | -The validator checks required files, YAML and JSON syntax, the Hermes distribution manifest, environment variable documentation, skill frontmatter, common secret patterns, broken symlinks, and unresolved template placeholders. |
| 53 | +## Environment |
120 | 54 |
|
121 | | -## Publish a generated profile |
| 55 | +No credential is required just to install the profile. Interactive model use requires any Hermes-supported model provider. Optional variables are documented in `.env.EXAMPLE`. |
122 | 56 |
|
123 | | -From the generated profile directory: |
| 57 | +## Validate |
124 | 58 |
|
125 | 59 | ```bash |
126 | | -git init -b main |
127 | | -git add . |
128 | | -git commit -m "feat: initial profile" |
129 | | -git remote add origin git@github.com:YOUR_ORG/YOUR_PROFILE_REPO.git |
130 | | -git push -u origin main |
| 60 | +python3 scripts/validate_profile.py . |
| 61 | +python3 -m py_compile scripts/*.py |
131 | 62 | ``` |
132 | 63 |
|
133 | | -Users can install it with: |
| 64 | +Generator smoke test: |
134 | 65 |
|
135 | 66 | ```bash |
136 | | -hermes profile install github.com/YOUR_ORG/YOUR_PROFILE_REPO --alias |
| 67 | +out=$(mktemp -d /tmp/context-forge-rag.XXXXXX) |
| 68 | +python3 scripts/generate_profile.py --params templates/profile.params.yaml --output "$out" |
| 69 | +python3 "$out/scripts/validate_profile.py" "$out" |
137 | 70 | ``` |
138 | 71 |
|
139 | | -## What to customize |
140 | | - |
141 | | -Most users should start with these files: |
142 | | - |
143 | | -- `SOUL.md`: the profile's identity, mission, boundaries, and output style. |
144 | | -- `distribution.yaml`: name, version, description, env vars, and distribution-owned files. |
145 | | -- `config.yaml`: model, toolsets, terminal behavior, memory, security, and approval defaults. |
146 | | -- `.env.EXAMPLE`: documented environment variables with placeholder values only. |
147 | | -- `skills/`: bundled reusable procedures the profile can load. |
148 | | -- `AGENTS.md`: instructions for AI coding agents that maintain the profile repository. |
149 | | - |
150 | | -Never commit `.env`, API keys, OAuth tokens, credentials, memories, sessions, logs, runtime databases, or private user data. |
151 | | - |
152 | | -## License |
| 72 | +## Security |
153 | 73 |
|
154 | | -MIT. See `LICENSE`. |
| 74 | +Never commit `.env`, API keys, OAuth tokens, session dumps, private documents, runtime memories, or customer data. The profile is designed to make architecture and implementation artifacts safer, more observable, and easier to evaluate. |
0 commit comments