Career Draft CLI

Important: This document describes the target state of the Career Draft CLI application.
It is not a description of the current implemented state.
The purpose of this document is to define what the application is intended to become.

---

1. Application Summary

Career Draft is intended to be a command-line, AI-assisted career profile and resume content builder.

The application will run as a Spring Shell CLI application. A user will start an interactive chat-like interview from the terminal. The system will then guide the user one question at a time, collect career information, validate the quality of responses, help the user improve weak answers, and gradually build a structured Career Profile JSON/YAML/POJO.

The final goal is to generate a clean, ATS-friendly, text-based resume draft that the user can copy into any resume template or format manually.

This is not intended to be a simple form-filling CLI. The target experience is closer to a career coach inside the terminal.

---

2. Target Product Behavior

The application should:

1. Run from the command line using Spring Shell.
2. Start with a command such as start.
3. Ask the user one question at a time.
4. Dynamically decide the next best question based on what is already known.
5. Store the user's information in a structured Career Profile JSON/YAML/POJO.
6. Allow the user to answer naturally, ask for help, correct earlier information, skip questions, or request resume generation.
7. Validate each answer for completeness, specificity, credibility, and resume usefulness.
8. Challenge vague answers and help the user improve them with examples.
9. Store safe partial facts even when the answer is incomplete.
10. Ask for confirmation before applying destructive corrections.
11. Use LLM agents for reasoning, classification, validation, coaching, and extraction.
12. Use Java/Spring services as the source of truth for state, persistence, and orchestration.
13. Store conversations, profile state, generated resume content, and agent traces in SQLite.
14. Generate one standard ATS-friendly text resume as the final output.

---

3. Target Technology Stack

The target application should use:

Area	Target Technology
CLI framework	Spring Shell
AI framework	Spring AI
Language	Java
Build tool	Maven
Persistence	SQLite
LLM provider	Any OpenAI-compatible model provider
Model configuration	Bring-your-own base URL, model, and API key
Search support	Optional, pluggable web search providers
Output format	Plain text resume content

The application should support working without web search, but it should also be designed so that web search providers can be added later.

---

4. Target Career Profile JSON

The core memory object of the application is the Career Profile.

This object represents facts about the user. It should not contain runtime-only data such as current question, pending confirmations, validation state, or generated resume versions.

Those runtime concerns should be stored separately in session/interview tables.

Career Profile JSON

{
  "personalInfo": {
    "fullName": null,
    "email": null,
    "phone": null,
    "location": null,
    "linkedInUrl": null,
    "githubUrl": null,
    "portfolioUrl": null
  },
  "targetRole": {
    "primaryRoleType": null,
    "seniorityLevel": null,
    "targetJobDescription": null
  },
  "professionalSummary": {
    "userProvidedSummary": null
  },
  "workExperiences": [
    {
      "companyName": null,
      "location": null,
      "startDate": null,
      "endDate": null,
      "currentRole": false,
      "positions": [
        {
          "jobTitle": "",
          "startDate": null,
          "endDate": null,
          "bulletPoints": []
        }
      ]
    }
  ],
  "skills": {
    "languages": [],
    "frameworks": [],
    "databases": [],
    "cloud": [],
    "devOps": [],
    "testing": [],
    "tools": [],
    "architecture": []
  },
  "education": [
    {
      "institutionName": null,
      "degree": null,
      "fieldOfStudy": null,
      "location": null,
      "startDate": null,
      "endDate": null,
      "grade": null,
      "relevantCoursework": []
    }
  ],
  "certifications": [
    {
      "name": null,
      "issuingOrganization": null,
      "issueDate": null,
      "expiryDate": null,
      "credentialUrl": null
    }
  ],
  "openSource": [
    {
      "projectName": null,
      "projectUrl": null,
      "contributionSummary": null,
      "technologies": [],
      "impact": null
    }
  ]
}

---

5. Target Runtime State

The Career Profile JSON stores candidate facts only.

The following information should be stored separately as runtime/application state:

• Current interview session
• Last assistant question
• Current focus field
• Pending correction confirmation
• Validation results
• Agent traces
• Raw chat messages
• Generated resume versions
• Model configuration
• Search configuration

This separation keeps the Career Profile clean and makes the application easier to debug and evolve.

---

6. Target Agent Architecture

The target application should use multiple specialized agents, coordinated by a Java/Spring orchestrator.

Agents should not directly write to SQLite or mutate the Career Profile. Agents should return structured outputs. The orchestrator should decide what to store, update, confirm, or reject.

Target Agents (Probable - Need to work on this part more)

1. Question Planner Agent
2. Response Classifier Agent
3. Help Coach Agent
4. Answer Validator / Critic Agent
5. Profile Extractor Agent
6. Improvement Coach Agent
7. Resume Writer Agent

---

7. Agent Responsibilities

7.1 Question Planner Agent

The Question Planner Agent decides the next best question to ask.

It should consider:

• Current Career Profile JSON
• Missing fields
• Current section
• Current focus
• Previous user answers
• Validation issues
• Target role
• Whether the user needs coaching or direct questioning

It should ask only one question at a time.

Example output:

{
  "nextQuestion": "What role are you targeting first?",
  "questionPurpose": "Identify target role before collecting experience details.",
  "targetField": "targetRole.primaryRoleType",
  "currentSection": "targetRole"
}

---

7.2 Response Classifier Agent

The Response Classifier Agent reviews the user's message and determines what kind of message it is.

A user response may contain:

• Only an answer
• Only a question/help request
• Both answer and question
• Correction request
• Skip request
• Resume generation request
• Unclear response

Example:

User says:

I worked at Infosys as a Java developer. Also, what should I say if I don't remember metrics?

Classifier output:

{
  "messageType": "answer_plus_question",
  "containsAnswer": true,
  "containsQuestion": true,
  "containsCorrection": false,
  "containsGenerateResumeRequest": false,
  "answerPart": "I worked at Infosys as a Java developer.",
  "questionPart": "What should I say if I don't remember metrics?",
  "confidence": 0.94
}

---

7.3 Help Coach Agent

The Help Coach Agent answers user questions and helps the user understand how to respond.

It should use the full conversation context and Career Profile state.

Example user message:

I don't know what to write for impact.

Help Coach response:

No problem. Impact does not always mean revenue. For a backend developer, impact can mean improved latency, reduced errors, fewer manual steps, better reliability, faster deployments, better monitoring, or easier maintenance.

For your project, did you improve speed, reduce errors, automate something, support more users, or make the system easier to maintain?

The Help Coach should not update the Career Profile directly.

---

7.4 Answer Validator / Critic Agent

The Answer Validator Agent reviews whether the user's answer is strong enough.

It should check:

• Completeness
• Specificity
• Credibility
• Technical depth
• Resume usefulness
• Consistency with previous answers
• Whether the answer contains measurable impact
• Whether the answer is too vague

Example weak answer:

I worked on APIs.

Validation output:

{
  "status": "weak",
  "canStorePartialFacts": true,
  "issues": [
    "Too generic",
    "No technology stack",
    "No project context",
    "No impact or scale"
  ],
  "storeableFacts": [
    "User worked on APIs"
  ],
  "needsImprovement": true,
  "suggestedImprovementFocus": "Ask what kind of APIs and who used them."
}

Example strong answer:

I built Spring Boot APIs for payment reconciliation used by internal finance teams. I optimized PostgreSQL queries and reduced report generation time from 12 minutes to 3 minutes.

Validation output:

{
  "status": "good",
  "canStorePartialFacts": true,
  "issues": [],
  "storeableFacts": [
    "Built Spring Boot APIs for payment reconciliation",
    "Used PostgreSQL",
    "Reduced report generation time from 12 minutes to 3 minutes"
  ],
  "needsImprovement": false
}

---

7.5 Profile Extractor Agent

The Profile Extractor Agent converts a validated answer into a structured patch for the Career Profile JSON.

It should extract facts only from what the user actually said.

It should not invent:

• Dates
• Companies
• Metrics
• Job titles
• Technologies
• Achievements
• Education details

Example output:

{
  "patch": {
    "workExperiences": [
      {
        "companyName": "Infosys",
        "jobTitle": "Java Developer",
        "projects": [
          {
            "description": "Payment reconciliation APIs",
            "techStack": ["Spring Boot", "PostgreSQL"],
            "impacts": [
              {
                "area": "performance",
                "description": "Reduced report generation time",
                "beforeValue": "12",
                "afterValue": "3",
                "metricUnit": "minutes",
                "confidence": "high"
              }
            ]
          }
        ]
      }
    ]
  },
  "confidence": 0.92,
  "requiresConfirmation": false
}

The orchestrator is responsible for merging this patch into the Career Profile JSON.

---

7.6 Improvement Coach Agent

The Improvement Coach Agent is called when the answer is weak or incomplete.

Its job is to help the user improve the answer by asking a better follow-up question and giving useful examples.

Example:

User says:

I worked on backend.

Improvement Coach response:

That is a useful start, but it is too broad for a strong resume. Backend work can mean many things.

Which of these best matches what you did?
1. Built REST APIs
2. Worked on database queries
3. Integrated third-party systems
4. Fixed production issues
5. Improved performance
6. Added authentication or security
7. Wrote tests or CI/CD pipelines

Pick one or describe it in your own words.

The Improvement Coach is different from the Question Planner.

• Question Planner asks the next normal resume question.
• Improvement Coach helps repair a weak answer.

---

7.7 Resume Writer Agent

The Resume Writer Agent generates the final ATS-friendly text resume.

It should use only facts from the Career Profile JSON and approved/generated content.

It should not invent:

• Companies
• Dates
• Degrees
• Metrics
• Technologies
• Certifications
• Job titles

Target output:

FULL NAME
Target Role
Email | Phone | Location | LinkedIn | GitHub

SUMMARY
...

TECHNICAL SKILLS
...

EXPERIENCE
...

PROJECTS
...

EDUCATION
...

CERTIFICATIONS
...

---

8. Target Flow

8.1 Start Flow

1. User runs Spring Shell command:

   start

2. System initializes the session.

3. System loads or creates an empty Career Profile JSON.

4. System loads previous conversation context if resuming.

5. Question Planner Agent decides the first question.

6. Assistant asks the question in the terminal.

---

8.2 Normal Answer Flow

1. User responds with an answer.
2. Response Classifier Agent determines that the message contains an answer.
3. Answer Validator Agent reviews the quality of the answer.
4. If the answer is good enough:
   • Profile Extractor Agent creates a structured JSON patch.
   • Orchestrator merges the patch into Career Profile JSON.
   • Updated profile is persisted to SQLite.
   • Question Planner Agent decides the next question.
   • Assistant asks the next question.

Happy path summary:

User Answer
  -> Response Classifier
  -> Answer Validator
  -> Profile Extractor
  -> Orchestrator merges and stores
  -> Question Planner
  -> Assistant asks next question

---

8.3 Help-Only Flow

If the user asks a question instead of answering:

1. Response Classifier Agent detects a help/question request.
2. Help Coach Agent answers the user's question with context and examples.
3. Assistant asks the user to answer again or continue from the same question.

Flow:

User Help Request
  -> Response Classifier
  -> Help Coach
  -> Assistant provides guidance
  -> User responds again

---

8.4 Answer Plus Help Flow

If the user gives an answer and also asks a question:

1. Response Classifier Agent splits the answer part and question part.
2. Help Coach Agent answers the question part.
3. Answer Validator Agent validates the answer part.
4. Profile Extractor Agent extracts profile facts from the answer part.
5. Orchestrator stores the extracted facts.
6. Question Planner Agent decides the next question.
7. Assistant responds with both help and the next question.

Flow:

User Message
  -> Response Classifier
  -> Help Coach handles question part
  -> Answer Validator handles answer part
  -> Profile Extractor extracts facts
  -> Orchestrator stores facts
  -> Question Planner decides next question
  -> Assistant responds

---

8.5 Weak Answer Flow

If the answer is weak, vague, or incomplete:

1. Response Classifier Agent detects an answer.
2. Answer Validator Agent marks it as weak.
3. Profile Extractor Agent may still extract safe partial facts.
4. Orchestrator stores safe partial facts if appropriate.
5. Improvement Coach Agent asks a better follow-up question with examples.
6. User gets help to produce a stronger answer.

Flow:

Weak User Answer
  -> Response Classifier
  -> Answer Validator marks weak
  -> Profile Extractor extracts safe partial facts
  -> Orchestrator stores partial facts
  -> Improvement Coach asks better follow-up

Example:

User: I worked on APIs.

Assistant: That is a useful start, but it is too generic for a strong resume. What kind of APIs were these, and who used them? For example, were they payment APIs, internal admin APIs, customer-facing APIs, reporting APIs, or integration APIs?

---

8.6 Correction Flow

If the user wants to correct existing information:

1. Response Classifier Agent detects a correction request.
2. Profile Extractor Agent creates a proposed correction patch.
3. Orchestrator stores it as a pending correction.
4. Assistant asks for confirmation before changing the Career Profile.
5. If user confirms, the orchestrator applies the patch.
6. If user rejects, the patch is discarded.

Flow:

Correction Request
  -> Response Classifier
  -> Profile Extractor creates proposed patch
  -> Orchestrator stores pending correction
  -> Assistant asks confirmation
  -> User confirms/rejects
  -> Orchestrator applies or discards patch

Example:

User: Actually my company was TCS, not Infosys.

Assistant: Just to confirm, should I replace "Infosys" with "TCS" for your current work experience?

---

8.7 Resume Generation Flow

If the user asks to generate the resume:

1. Response Classifier Agent detects a resume generation request.
2. Orchestrator checks whether enough information exists.
3. If information is insufficient, Question Planner or Improvement Coach asks for missing high-value details.
4. If sufficient, the system shows a review summary.
5. User confirms generation.
6. Resume Writer Agent generates the ATS-friendly text resume.
7. Generated resume is stored in SQLite.
8. Resume text is printed in the terminal.

Flow:

Generate Resume Request
  -> Response Classifier
  -> Completeness check
  -> Review summary
  -> User confirmation
  -> Resume Writer Agent
  -> Store generated resume
  -> Print final text resume

---

9. Orchestrator Responsibilities

The orchestrator is a Spring service that controls the flow.

It should:

• Load the current session.
• Load Career Profile JSON.
• Save raw user messages.
• Call agents in the correct order.
• Validate agent outputs.
• Merge profile patches.
• Persist updated state.
• Store redacted agent traces.
• Handle pending confirmations.
• Decide whether to continue, ask for help, or generate the resume.

Agents should never directly mutate the database.

---

10. Persistence Target

SQLite should store:

• Sessions
• Messages
• Career Profile JSON
• Pending actions
• Agent traces
• Model configuration
• Search configuration
• Generated resumes

Suggested tables:

sessions
messages
career_profiles
pending_actions
agent_traces
model_configs
search_configs
generated_resumes

---

11. Key Design Rules

1. This is the target state, not the current implementation.
2. Ask only one question at a time.
3. Career Profile JSON stores candidate facts only.
4. Runtime state is stored separately.
5. Agents do not update the database directly.
6. The orchestrator owns state transitions.
7. Weak answers should be improved, not simply rejected.
8. Safe partial facts may be stored even when the answer is incomplete.
9. Destructive corrections require immediate confirmation.
10. The system should behave like a career coach, not a rigid form.
11. The final output is plain text ATS-friendly resume content.
12. The system should support OpenAI-compatible models through user-provided configuration.
13. Search should be optional and pluggable.
14. Agent traces should be stored with secrets redacted.

---

12. Target Flow Summary

start command
  -> initialize session
  -> load/create Career Profile JSON
  -> Question Planner asks first question
  -> user responds
  -> Response Classifier detects intent
  -> Help Coach handles questions if present
  -> Answer Validator checks answer quality
  -> Profile Extractor creates JSON patch
  -> Orchestrator stores safe facts
  -> Improvement Coach helps if answer is weak
  -> Question Planner asks next question
  -> repeat until profile is strong enough
  -> show review summary
  -> Resume Writer generates ATS-friendly text resume

---

13. End Goal

The target end state is a local-first CLI application where a developer can have a natural conversation with an AI career coach, gradually build a structured Career Profile, improve weak career descriptions, and generate high-quality resume content without manually filling a long form.

The application should feel conversational to the user, but internally it should behave like a structured, validated, resumable career profile builder.