Skip to content

Getting Started ​

This guide walks you through the complete workflow — from a raw idea file to a polished, reviewed, and revised blog post.

Prerequisites ​

  • Node.js >= 18
  • A markdown file with your raw ideas (e.g., my-idea.md)
  • (Optional) An API key for an AI provider to generate real content

1. Clone the Repository ​

bash
git clone https://github.com/mmornati/ai-brief.git
cd ai-brief

2. Configure an AI Provider ​

The pipeline needs an AI to generate content. Set up an OpenAI-compatible provider:

Option A: .env file (recommended)

Copy the example file and fill in your values:

bash
cp .env.example .env

Edit .env:

bash
AI_API_KEY=sk-your-api-key-here
AI_BASE_URL=https://api.openai.com/v1
AI_MODEL=gpt-4o-mini

The .env file is automatically loaded when running any CLI command.

Option B: Environment variables

bash
# Required: your API key
export AI_API_KEY=your-api-key-here

# Optional: custom endpoint (default: https://api.openai.com/v1)
# For local models via Ollama: export AI_BASE_URL=http://localhost:11434/v1
export AI_BASE_URL=https://api.openai.com/v1

# Optional: model selection (default: gpt-4o-mini)
export AI_MODEL=gpt-4o-mini

Supported providers (pass via --provider):

ProviderDescription
passthroughEchoes prompts as output (no AI, for testing)
openai-compatibleOpenAI API or any compatible endpoint (OpenAI, Ollama, OpenRouter, LocalAI, etc.)

3. Create an Input File ​

Create a markdown file with your content idea. This can be as rough as bullet points or free-form notes — the pipeline will validate, research, and structure it:

markdown
# My Blog Post Idea

Topic: How AI coding assistants are changing developer workflows

Key points:
- Less boilerplate, more architecture thinking
- Shift from writing code to reviewing code
- New skills developers need to develop

Target audience: Senior developers and tech leads
Tone: Professional but approachable

4. Run the Pipeline ​

bash
# With AI generation:
node src/cli.js run my-idea.md --format blog --provider openai-compatible

The pipeline executes six steps sequentially (validate → research → structure → write → format → review). Each step calls the AI and prints its thinking to the console.

5. View the Results ​

After the pipeline completes, two output files are produced:

FileContents
ai-brief-output/blog/my-idea-blog.mdThe complete blog post
ai-brief-output/my-idea-review.mdA separate review report evaluating the final blog post

The review report is generated by the final pipeline step. It evaluates the blog post critically — checking factual accuracy, clarity, structure, and style. It is saved as a separate file so you can read it independently.

6. Review and Revise ​

Read the review report to see what improvements were suggested. You have two options for revising the blog post:

Option A: Use the auto-generated review

The review from step 6 already contains expert feedback. You can apply it immediately:

bash
node src/cli.js revise my-idea.md --format blog --provider openai-compatible

This reads the format step output and the auto-generated review, calls the AI to address every issue, and saves the revised blog post.

Option B: Add your own feedback

You can edit the review file to add your own comments, then run revise with it:

bash
# Edit the review to add your own feedback
# - Keep any issues you agree with
# - Remove issues you disagree with
# - Add your own comments or suggestions
vim ai-brief-output/my-idea-review.md

# Run revise — it will use your edited review
node src/cli.js revise my-idea.md --format blog --provider openai-compatible

Option C: Provide your own feedback file

You can write your own review file from scratch:

bash
# Write your feedback (any markdown format)
cat > my-feedback.md << 'EOF'
# My Feedback

I'd like the introduction to be more concise.
Please add a comparison table in section 3.
EOF

# Run revise with your custom feedback
node src/cli.js revise my-idea.md --format blog --provider openai-compatible --review-file my-feedback.md

7. Complete Workflow Summary ​

1. Write idea.md (raw notes)
2. ai-brief run idea.md --format blog --provider openai-compatible   # produces blog + review
3. Read ai-brief-output/idea-review.md                               # review the feedback
4. (Optional) Edit the review file to add your own comments
5. ai-brief revise idea.md --format blog --provider openai-compatible  # incorporate feedback
6. Read ai-brief-output/blog/idea-blog.md                              # final revised blog post

Next Steps ​

MIT License — Built with ❤️ by mmornati