Skip to content

Commit bc6d46f

Browse files
author
Akki Parekh
committed
Parking changes for improvements for docs
1 parent 5728b29 commit bc6d46f

22 files changed

Lines changed: 1535 additions & 32 deletions

‎README.md‎

Lines changed: 59 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -372,30 +372,53 @@ Angular 17 introduced Signals as a stable reactive primitive...
372372

373373
## How It Works
374374

375+
```mermaid
376+
flowchart TD
377+
A["Transcript Input\n(--file input/tutorial.md)"] --> B["Safety / Intake Guard\n(URL validate · tech classify · transcript check)"]
378+
B --> C["Mode Selector\n(--type docusaurus|blog|faq|...)"]
379+
C --> D["Prompt Builder\n(_shared.md + _profile.md + mode.md + config)"]
380+
D --> E["Provider Adapter\nmock | OpenAI | Anthropic | Gemini"]
381+
E --> F["Markdown Generator\n(index.md · docs/{slug}.md)"]
382+
F --> G["Review Checklist\n(review-checklist.md · metadata.json · source-summary.md)"]
383+
G --> H["Docs Site\n(Docusaurus · GitBook · GitHub · Blog)"]
375384
```
376-
Transcript / Notes
377-
↓
378-
Source Parser
379-
(extract title, source URL, content)
380-
↓
381-
Video Intake Guard (if --url provided)
382-
(URL validate → metadata fetch → tech classify)
383-
↓
384-
Mode Prompt Builder
385-
(shared rules + user profile + mode template)
386-
↓
387-
Provider Adapter
388-
(mock / OpenAI / Anthropic / Gemini)
389-
↓
390-
Markdown Generator
391-
(index.md + type-specific files)
392-
↓
393-
Review Checklist
394-
(review-checklist.md + metadata.json)
395-
↓
396-
Output Files
397-
(output/{slug}-{date}/)
398-
```
385+
386+
---
387+
388+
## What This Proves
389+
390+
> For recruiters, hiring managers, and anyone evaluating AI developer tooling skills.
391+
392+
devdocs-forge-agent is not a toy project. It is a working CLI tool with a real user experience, a test suite, CI/CD, and documentation — built to demonstrate specific engineering capabilities:
393+
394+
| Capability | Where to Look |
395+
|---|---|
396+
| **Provider abstraction pattern** | `src/providers/provider.types.ts` + `provider-registry.ts` — one interface, four implementations, zero coupling |
397+
| **Pipeline orchestration** | `src/pipeline/generation-pipeline.ts` — clear single-responsibility stages |
398+
| **Prompt engineering as code** | `modes/` folder — modular, human-editable prompt files that non-engineers can contribute to |
399+
| **Zod schema validation** | `src/config/config.schema.ts` — typed config with clear error messages |
400+
| **CLI design with Commander.js** | `src/cli/index.ts` + 10 command files |
401+
| **Native fetch, no SDK bloat** | `src/providers/openai.provider.ts` — auditable, minimal, fast install |
402+
| **AI-safe output design** | Every run produces `review-checklist.md` + `metadata.json` with `reviewRequired: true` |
403+
| **Test suite without mocking FS** | `tests/` — 9 test files covering core logic |
404+
| **CI on 4 environments** | Ubuntu + macOS × Node 22 + 24 |
405+
406+
Run the project in 5 minutes: `git clone` → `npm install` → `npm run demo`.
407+
408+
See [`docs/recruiter-review-guide.md`](docs/recruiter-review-guide.md) for a full evaluation walkthrough.
409+
410+
---
411+
412+
## Why Developers Star This
413+
414+
- **Zero-config demo** — `npm run demo` works with no API key, generates real output
415+
- **BYO model** — OpenAI, Anthropic, Gemini, or local Ollama (planned) — no provider lock-in
416+
- **Markdown-first** — outputs drop directly into Docusaurus, GitBook, GitHub, or any Markdown-based docs site
417+
- **Prompt engineering as text files** — the `modes/` folder is plain Markdown, not code. Anyone can improve the prompts
418+
- **Review-first by design** — every output includes a human review checklist before publishing
419+
- **Agent-friendly** — `AGENTS.md` and `CLAUDE.md` make AI-assisted development workflows first-class
420+
- **9 labeled good first issues** — contributor onramp is real, not aspirational
421+
- **Local-first, no telemetry** — nothing leaves your machine except your own API calls
399422

400423
---
401424

@@ -468,13 +491,19 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup instructions.
468491

469492
## Good First Issues
470493

471-
| Issue | Description |
472-
|------------------------------------------------------------------------------------------------------|------------------------|
473-
| [#1 Ollama provider](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/1) | Add local LLM support |
474-
| [#2 OpenRouter provider](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/2) | Access 200+ models |
475-
| [#3 Mermaid diagram mode](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/3) | New output mode |
476-
| [#4 Improve Docusaurus frontmatter](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/4) | Smarter tag extraction |
477-
| [#5 Minimal web preview](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/5) | Browser preview |
494+
| Issue | Description | Difficulty |
495+
|---|---|---|
496+
| [#1 Ollama provider](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/1) | Add local LLM support — no API key | Low (~80 lines) |
497+
| [#2 OpenRouter provider](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/2) | Access 200+ models via unified API | Low (~60 lines) |
498+
| [#3 Mermaid diagram mode](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/3) | New `--type diagram` output mode | Low (prompt + config) |
499+
| [#4 Improve Docusaurus frontmatter](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/4) | Custom fields, tag merging, draft support | Low–Medium |
500+
| [#5 Minimal web preview](https://github.com/AnkitParekh007/devdocs-forge-agent/issues/5) | `npm run preview` browser preview | Medium |
501+
| GitBook export polish | Hint blocks, page-refs, tab blocks | Low (prompt work) |
502+
| Docusaurus sidebar helper | Auto-generate sidebar config snippet | Low–Medium |
503+
| Transcript chunking | Split long transcripts for LLM context limits | Medium |
504+
| Docs quality score | Heuristic quality score in `npm run verify` | Medium |
505+
506+
See [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) for full specs and acceptance criteria.
478507

479508
---
480509

‎docs/ARCHITECTURE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,24 @@
11
# Architecture
22

3+
## Pipeline Diagram
4+
5+
```mermaid
6+
flowchart TD
7+
A["Transcript Input\n(--file input/tutorial.md)"] --> B["Safety / Intake Guard\n(URL validate · tech classify · transcript check)"]
8+
B --> C["Mode Selector\n(--type docusaurus|blog|faq|...)"]
9+
C --> D["Prompt Builder\n(_shared.md + _profile.md + mode.md + config)"]
10+
D --> E["Provider Adapter\nmock | OpenAI | Anthropic | Gemini"]
11+
E --> F["Markdown Generator\n(index.md · docs/{slug}.md)"]
12+
F --> G["Review Checklist\n(review-checklist.md · metadata.json · source-summary.md)"]
13+
G --> H["Docs Site\n(Docusaurus · GitBook · GitHub · Blog)"]
14+
15+
style A fill:#f0f4ff,stroke:#4a6fa5
16+
style B fill:#fff3cd,stroke:#d4881a
17+
style E fill:#e8f5e9,stroke:#388e3c
18+
style G fill:#fce4ec,stroke:#c62828
19+
style H fill:#e8eaf6,stroke:#3949ab
20+
```
21+
322
## System Overview
423

524
```

‎docs/GOOD_FIRST_ISSUES.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,88 @@ Full issue: [.github/ISSUE_TEMPLATES_READY/05-build-minimal-web-preview.md](../.
101101

102102
---
103103

104+
### 6. GitBook Export Polish
105+
106+
**Title:** Polish GitBook output mode formatting
107+
**Labels:** `good first issue`, `mode`, `documentation`
108+
**Difficulty:** Low (prompt engineering + template work, minimal TypeScript)
109+
110+
The `--type gitbook` mode generates valid Markdown but misses some GitBook-specific conventions: hint blocks (`{% hint style="info" %}`), page-ref cards, and tab blocks. Improve the mode prompt and add an example output.
111+
112+
Key files:
113+
- `modes/gitbook.md` — update prompt with GitBook-specific formatting instructions
114+
- `examples/` — add a sample GitBook output showing hint blocks
115+
- `docs/MODES.md` — document the GitBook-specific output features
116+
117+
Acceptance criteria:
118+
- Generated GitBook output uses `{% hint %}` blocks for notes and warnings
119+
- Output renders correctly in a local GitBook project
120+
- Example output added to `examples/`
121+
122+
---
123+
124+
### 7. Docusaurus Sidebar Helper
125+
126+
**Title:** Add Docusaurus sidebar.js snippet generator
127+
**Labels:** `good first issue`, `docusaurus`, `enhancement`
128+
**Difficulty:** Low to medium (TypeScript, file reading)
129+
130+
After running `npm run batch`, users manually update their Docusaurus `sidebars.js`. Add a command that reads the `output/` directory and prints a ready-to-paste sidebar config snippet.
131+
132+
Key files:
133+
- Create `src/cli/commands/sidebar.command.ts`
134+
- Register in `src/cli/index.ts`
135+
- Add `npm run sidebar` script to `package.json`
136+
137+
Acceptance criteria:
138+
- `npm run sidebar` prints a valid Docusaurus sidebar config snippet to stdout
139+
- Snippet includes all `docs/{slug}.md` files found in `output/`
140+
- Works with zero additional config
141+
142+
---
143+
144+
### 8. Transcript Chunking for Long Videos
145+
146+
**Title:** Add transcript chunking for long transcripts
147+
**Labels:** `good first issue`, `pipeline`, `enhancement`
148+
**Difficulty:** Medium (~100 lines, involves pipeline changes)
149+
150+
Long transcripts (>8,000 tokens) exceed typical LLM context windows. Add a chunking strategy that splits long transcripts into sections, generates per-section docs, and merges them into a single output.
151+
152+
Key files:
153+
- Create `src/pipeline/transcript-chunker.ts`
154+
- Update `src/pipeline/generation-pipeline.ts` to call chunker when transcript exceeds a threshold
155+
- Add chunking config option to `src/config/config.schema.ts`
156+
157+
Acceptance criteria:
158+
- Transcripts under the threshold are processed unchanged
159+
- Transcripts over the threshold are split at section boundaries (H2 headings)
160+
- Merged output is a single valid Markdown document
161+
- `metadata.json` records `chunked: true` and chunk count
162+
163+
---
164+
165+
### 9. Docs Quality Score
166+
167+
**Title:** Add documentation quality score to verify output
168+
**Labels:** `good first issue`, `pipeline`, `enhancement`
169+
**Difficulty:** Medium (~80 lines, heuristic scoring)
170+
171+
`npm run verify` currently checks for required files. Add a quality score (0–100) based on heuristics: heading count, code block count, word count, checklist completeness, frontmatter completeness.
172+
173+
Key files:
174+
- Create `src/pipeline/quality-scorer.ts`
175+
- Update `src/cli/commands/verify.command.ts` to display the score
176+
- Add score to `metadata.json`
177+
178+
Acceptance criteria:
179+
- `npm run verify` displays a quality score for each output directory
180+
- Score is between 0 and 100
181+
- Score is written to `metadata.json` as `qualityScore`
182+
- Documented scoring criteria in `docs/output-contract.md`
183+
184+
---
185+
104186
## Creating These as GitHub Issues
105187

106188
If you are the maintainer, use GitHub CLI to create these issues:
@@ -130,6 +212,27 @@ gh issue create \
130212
--title "Build minimal local web preview for generated docs" \
131213
--body-file ".github/ISSUE_TEMPLATES_READY/05-build-minimal-web-preview.md" \
132214
--label "good first issue,frontend,enhancement"
215+
216+
# New issues (v0.1.1)
217+
gh issue create \
218+
--title "Polish GitBook output mode formatting" \
219+
--label "good first issue,mode,documentation" \
220+
--body "See docs/GOOD_FIRST_ISSUES.md issue #6 for full spec."
221+
222+
gh issue create \
223+
--title "Add Docusaurus sidebar snippet generator" \
224+
--label "good first issue,docusaurus,enhancement" \
225+
--body "See docs/GOOD_FIRST_ISSUES.md issue #7 for full spec."
226+
227+
gh issue create \
228+
--title "Add transcript chunking for long videos" \
229+
--label "good first issue,pipeline,enhancement" \
230+
--body "See docs/GOOD_FIRST_ISSUES.md issue #8 for full spec."
231+
232+
gh issue create \
233+
--title "Add docs quality score to verify command" \
234+
--label "good first issue,pipeline,enhancement" \
235+
--body "See docs/GOOD_FIRST_ISSUES.md issue #9 for full spec."
133236
```
134237

135238
> Note: GitHub labels must exist before using `--label`. Create them first in the Labels settings page or with `gh label create "good first issue" --color "#7057ff"`.

‎docs/output-contract.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Output Contract
2+
3+
Every `generate` or `batch` run produces a timestamped output directory with a guaranteed file set. This document defines what those files contain and what consumers can rely on.
4+
5+
## Directory Structure
6+
7+
```
8+
output/{slug}-{YYYY-MM-DD}/
9+
├── index.md ← Primary generated documentation
10+
├── metadata.json ← Machine-readable generation record
11+
├── review-checklist.md ← Human review tasks
12+
├── source-summary.md ← Source attribution and stats
13+
└── docs/ ← (docusaurus mode only)
14+
└── {slug}.md ← Docusaurus-ready copy with YAML frontmatter
15+
```
16+
17+
The `docs/` subdirectory is only created when `--type docusaurus` is used.
18+
19+
## File Specifications
20+
21+
### `index.md`
22+
23+
The primary generated document. Contains:
24+
25+
- Markdown body matching the requested output mode
26+
- Source attribution comment at the bottom
27+
- A "Review Checklist" section embedded in the document
28+
29+
**Consumers:** human review, Git history, docs site ingestion.
30+
31+
### `metadata.json`
32+
33+
Machine-readable generation record. Schema:
34+
35+
```typescript
36+
{
37+
provider: string; // "mock" | "openai" | "anthropic" | "gemini"
38+
model: string; // exact model ID used
39+
mode: string; // output mode (docusaurus, blog, faq, etc.)
40+
sourceFile: string; // path to input transcript
41+
sourceUrl: string | null; // video URL if --url was provided
42+
title: string; // extracted or inferred title
43+
slug: string; // URL-safe slug derived from title
44+
wordCount: number; // word count of input transcript
45+
outputWordCount: number; // word count of generated document
46+
generatedAt: string; // ISO 8601 timestamp
47+
outputDir: string; // path to this output directory
48+
reviewRequired: true; // always true — never false
49+
intakeGuard: {
50+
urlValidated: boolean;
51+
techClassificationScore: number | null; // 0.0–1.0 or null if no URL
52+
transcriptWordCount: number;
53+
passed: boolean;
54+
};
55+
}
56+
```
57+
58+
**Consumers:** `npm run verify`, CI pipelines, audit logs.
59+
60+
### `review-checklist.md`
61+
62+
A Markdown checklist of tasks a human reviewer should complete before publishing. Generated based on the output mode and source content.
63+
64+
**Consumers:** human reviewer, PR description templates.
65+
66+
### `source-summary.md`
67+
68+
Short summary of the source used in generation:
69+
70+
- Title
71+
- Source URL (if provided)
72+
- Word count
73+
- Slug
74+
- Generation timestamp
75+
76+
**Consumers:** attribution compliance, provenance tracking.
77+
78+
### `docs/{slug}.md` (docusaurus mode only)
79+
80+
A copy of the generated document with YAML frontmatter prepended, ready to copy into a Docusaurus `docs/` directory.
81+
82+
Frontmatter fields guaranteed: `id`, `title`, `sidebar_label`, `sidebar_position`, `description`, `tags`.
83+
84+
## Guarantees
85+
86+
| Property | Guarantee |
87+
|---|---|
88+
| `reviewRequired` in metadata.json | Always `true` — never omitted or `false` |
89+
| `review-checklist.md` | Always present in every output directory |
90+
| `metadata.json` | Always valid JSON, always present |
91+
| `index.md` | Always present, always Markdown |
92+
| File encoding | UTF-8 |
93+
| Line endings | LF (`\n`) |
94+
95+
## What Is Not Guaranteed
96+
97+
- Content accuracy — AI output is a first draft; always review
98+
- Code correctness — all generated code should be tested before use
99+
- Completeness — transcripts with insufficient content may produce short outputs
100+
- Stability of `metadata.json` schema across major versions — check CHANGELOG.md
101+
102+
## Validation
103+
104+
Run `npm run verify` to validate all output directories against this contract. The verify command checks:
105+
106+
- Required files are present
107+
- `metadata.json` is valid JSON with required fields
108+
- `index.md` contains a review checklist section
109+
- No empty output files
110+
111+
See `src/cli/commands/verify.command.ts` for the implementation.

0 commit comments

Comments
 (0)